Skip to content

Commit d71fd5d

Browse files
nathanfalkenathanfalke
committed
azure-defender-easm client initial commit
1 parent 587f44c commit d71fd5d

28 files changed

+24625
-0
lines changed

‎sdk/easm/azure-defender-easm/CHANGELOG.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Release History
2+
3+
## 1.0.0b1 (1970-01-01)
4+
5+
- Initial version

‎sdk/easm/azure-defender-easm/LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) Microsoft Corporation.
2+
3+
MIT License
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.

‎sdk/easm/azure-defender-easm/MANIFEST.in

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include *.md
2+
include LICENSE
3+
include azure/defender/easm/py.typed
4+
recursive-include tests *.py
5+
recursive-include samples *.py *.md
6+
include azure/__init__.py
7+
include azure/defender/__init__.py

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

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
2+
# EASM Data Plane Client library for Python
3+
*Microsoft Defender External Attack Surface Management (Defender EASM)* continuously discovers and maps your digital attack surface to provide an external view of your online infrastructure. This visibility enables security and IT teams to identify unknowns, prioritize risk, eliminate threats, and extend vulnerability and exposure control beyond the firewall. Defender EASM leverages Microsoft’s crawling technology to discover assets that are related to your known online infrastructure, and actively scans these assets to discover new connections over time. Attack Surface Insights are generated by leveraging vulnerability and infrastructure data to showcase the key areas of concern for your organization.
4+
5+
[Source Code][source_code] | [Package (pypi)][pypi] | [Api Reference Documentation][api_reference] | [Product Documentation][product_documentation]
6+
7+
## Getting started
8+
### Installing the package
9+
10+
#### pip
11+
```bash
12+
python -m pip install azure-defender-easm
13+
```
14+
15+
#### from source
16+
```bash
17+
python setup.py intall
18+
```
19+
20+
#### Prerequisites
21+
22+
- Python 3.7 or later is required to use this package.
23+
- You need an [Azure subscription][azure_sub] to use this package.
24+
- An existing EASM Data Plane Client instance.
25+
26+
#### Create with an Azure Active Directory Credential
27+
To use an [Azure Active Directory (AAD) token credential][authenticate_with_token],
28+
provide an instance of the desired credential type obtained from the
29+
[azure-identity][azure_identity_credentials] library.
30+
31+
To authenticate with AAD, you must first [pip][pip] install [`azure-identity`][azure_identity_pip]
32+
33+
After setup, you can choose which type of [credential][azure_identity_credentials] from azure.identity to use.
34+
As an example, [DefaultAzureCredential][default_azure_credential] can be used to authenticate the client:
35+
36+
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
37+
`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`
38+
39+
Use the returned token credential to authenticate the client:
40+
41+
```python
42+
from azure.defender.easm import EasmClient
43+
from azure.identity import DefaultAzureCredential
44+
45+
sub_id = '<your subscription ID here>'
46+
workspace_name = '<your workspace name here>'
47+
resource_group = '<your resource group here>'
48+
region = '<your region here>'
49+
50+
endpoint = f'{region}.easm.defender.microsoft.com'
51+
52+
client = EasmClient(endpoint, resource_group, sub_id, workspace_name, credential=DefaultAzureCredential())
53+
```
54+
55+
## Key concepts
56+
Basic understanding these terms will help to get started with EASM client library.
57+
58+
### [Assets][assets_documentation]
59+
Defender EASM includes the discovery of the following kinds of assets:
60+
- Domains
61+
- Hosts
62+
- Pages
63+
- IP Blocks
64+
- IP Addresses
65+
- Autonomous System Numbers (ASNs)
66+
- SSL Certificates
67+
- WHOIS Contacts
68+
69+
These asset types comprise your attack surface inventory in Defender EASM. This solution discovers externally facing assets that are exposed to the open internet outside of traditional firewall protection; they need to be monitored and maintained to minimize risk and improve an organization’s security posture. Microsoft Defender External Attack Surface Management (Defender EASM) actively discovers and monitors these assets, then surfacing key insights that help customers efficiently address any vulnerabilities in their organization.
70+
71+
### [Discovery][discovery_documentation]
72+
Microsoft Defender External Attack Surface Management (Defender EASM) relies on our proprietary discovery technology to continuously define your organization’s unique Internet-exposed attack surface. Discovery scans known assets owned by your organization to uncover previously unknown and unmonitored properties. Discovered assets are indexed in a customer’s inventory, providing a dynamic system of record of web applications, third party dependencies, and web infrastructure under the organization’s management through a single pane of glass.
73+
74+
#### [Discovery Groups][discovery_groups_documentation]
75+
Custom discoveries are organized into Discovery Groups. They are independent seed clusters that comprise a single discovery run and operate on their own recurrence schedules. Users can elect to organize their Discovery Groups to delineate assets in whatever way best benefits their company and workflows. Common options include organizing by responsible team/business unit, brands or subsidiaries.
76+
77+
## Examples
78+
After authenticating as shown in the "Create with an Azure Active Directory Credential" section, you can get started building your inventory like this:
79+
80+
### Create a discovery group
81+
```python
82+
from azure.defender.easm import EasmClient
83+
from azure.identity import DefaultAzureCredential
84+
85+
sub_id = '<your subscription ID here>'
86+
workspace_name = '<your workspace name here>'
87+
resource_group = '<your resource group here>'
88+
region = '<your region here>'
89+
90+
endpoint = f'{region}.easm.defender.microsoft.com'
91+
92+
client = EasmClient(endpoint, resource_group, sub_id, workspace_name, credential=DefaultAzureCredential())
93+
94+
client.disco_groups.put("example group", {
95+
'seeds': [
96+
{'kind': 'host', 'name': 'example.org'}
97+
]
98+
})
99+
client.disco_groups.run("example group")
100+
```
101+
102+
### View assets
103+
```python
104+
from azure.defender.easm import EasmClient
105+
from azure.identity import DefaultAzureCredential
106+
107+
sub_id = '<your subscription ID here>'
108+
workspace_name = '<your workspace name here>'
109+
resource_group = '<your resource group here>'
110+
region = '<your region here>'
111+
112+
endpoint = f'{region}.easm.defender.microsoft.com'
113+
114+
client = EasmClient(endpoint, resource_group, sub_id, workspace_name, credential=DefaultAzureCredential())
115+
116+
for asset in client.assets.list():
117+
print(f'{asset.kind}: {asset.name}')
118+
```
119+
120+
### More examples
121+
More examples can be viewed in the [samples directory][samples] of this repository
122+
123+
## Contributing
124+
This project welcomes contributions and suggestions. Most contributions require
125+
you to agree to a Contributor License Agreement (CLA) declaring that you have
126+
the right to, and actually do, grant us the rights to use your contribution.
127+
For details, visit https://cla.microsoft.com.
128+
129+
When you submit a pull request, a CLA-bot will automatically determine whether
130+
you need to provide a CLA and decorate the PR appropriately (e.g., label,
131+
comment). Simply follow the instructions provided by the bot. You will only
132+
need to do this once across all repos using our CLA.
133+
134+
This project has adopted the
135+
[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
136+
see the Code of Conduct FAQ or contact [email protected] with any
137+
additional questions or comments.
138+
139+
<!-- LINKS -->
140+
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
141+
[authenticate_with_token]: https://docs.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token
142+
[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials
143+
[azure_identity_pip]: https://pypi.org/project/azure-identity/
144+
[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
145+
[pip]: https://pypi.org/project/pip/
146+
[azure_sub]: https://azure.microsoft.com/free/
147+
[samples]: https://github.com/nathanfalke/azure-sdk-for-python/tree/main/sdk/easm/azure-defender-easm/samples
148+
[assets_documentation]: https://learn.microsoft.com/en-us/azure/external-attack-surface-management/understanding-inventory-assets
149+
[discovery_documentation]: https://learn.microsoft.com/en-us/azure/external-attack-surface-management/what-is-discovery
150+
[discovery_groups_documentation]: https://learn.microsoft.com/en-us/azure/external-attack-surface-management/using-and-managing-discovery#discovery-groups
151+
[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/easm/azure-defender-easm/
152+
[pypi]: https://pypi.org/project/azure-defender-easm/
153+
[api_reference]: https://review.learn.microsoft.com/en-us/rest/api/defenderforeasm/?branch=easm
154+
[product_documentation]: https://learn.microsoft.com/en-us/azure/external-attack-surface-management/

‎sdk/easm/azure-defender-easm/azure/__init__.py

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__path__ = __import__("pkgutil").extend_path(__path__, __name__) # type: ignore

‎sdk/easm/azure-defender-easm/azure/defender/__init__.py

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__path__ = __import__("pkgutil").extend_path(__path__, __name__) # type: ignore

‎sdk/easm/azure-defender-easm/azure/defender/easm/__init__.py

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# coding=utf-8
2+
# --------------------------------------------------------------------------
3+
# Copyright (c) Microsoft Corporation. All rights reserved.
4+
# Licensed under the MIT License. See License.txt in the project root for license information.
5+
# Code generated by Microsoft (R) AutoRest Code Generator.
6+
# Changes may cause incorrect behavior and will be lost if the code is regenerated.
7+
# --------------------------------------------------------------------------
8+
9+
from ._client import EasmClient
10+
from ._version import VERSION
11+
12+
__version__ = VERSION
13+
14+
try:
15+
from ._patch import __all__ as _patch_all
16+
from ._patch import * # pylint: disable=unused-wildcard-import
17+
except ImportError:
18+
_patch_all = []
19+
from ._patch import patch_sdk as _patch_sdk
20+
21+
__all__ = [
22+
"EasmClient",
23+
]
24+
__all__.extend([p for p in _patch_all if p not in __all__])
25+
26+
_patch_sdk()

‎sdk/easm/azure-defender-easm/azure/defender/easm/_client.py

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# coding=utf-8
2+
# --------------------------------------------------------------------------
3+
# Copyright (c) Microsoft Corporation. All rights reserved.
4+
# Licensed under the MIT License. See License.txt in the project root for license information.
5+
# Code generated by Microsoft (R) AutoRest Code Generator.
6+
# Changes may cause incorrect behavior and will be lost if the code is regenerated.
7+
# --------------------------------------------------------------------------
8+
9+
from copy import deepcopy
10+
from typing import Any, TYPE_CHECKING
11+
12+
from azure.core import PipelineClient
13+
from azure.core.rest import HttpRequest, HttpResponse
14+
15+
from ._configuration import EasmClientConfiguration
16+
from ._serialization import Deserializer, Serializer
17+
from .operations import (
18+
AssetsOperations,
19+
DiscoveryGroupsOperations,
20+
DiscoveryTemplatesOperations,
21+
ReportsOperations,
22+
SavedFiltersOperations,
23+
TasksOperations,
24+
)
25+
26+
if TYPE_CHECKING:
27+
# pylint: disable=unused-import,ungrouped-imports
28+
from azure.core.credentials import TokenCredential
29+
30+
31+
class EasmClient: # pylint: disable=client-accepts-api-version-keyword
32+
"""Defender EASM discovers and maps your digital attack surface to provide an "outside-in"
33+
perspective using probes to discover assets. The assets are provided with detailed metadata
34+
associated, including vulnerabilities, configurations and web components, allowing customers to
35+
view and prioritize external risk. The EASM REST API enables you to develop clients that
36+
integrate with your application.
37+
38+
:ivar assets: AssetsOperations operations
39+
:vartype assets: azure.defender.easm.operations.AssetsOperations
40+
:ivar discovery_groups: DiscoveryGroupsOperations operations
41+
:vartype discovery_groups: azure.defender.easm.operations.DiscoveryGroupsOperations
42+
:ivar discovery_templates: DiscoveryTemplatesOperations operations
43+
:vartype discovery_templates: azure.defender.easm.operations.DiscoveryTemplatesOperations
44+
:ivar reports: ReportsOperations operations
45+
:vartype reports: azure.defender.easm.operations.ReportsOperations
46+
:ivar saved_filters: SavedFiltersOperations operations
47+
:vartype saved_filters: azure.defender.easm.operations.SavedFiltersOperations
48+
:ivar tasks: TasksOperations operations
49+
:vartype tasks: azure.defender.easm.operations.TasksOperations
50+
:param endpoint: The endpoint hosting the requested resource. For example,
51+
{region}.easm.defender.microsoft.com. Required.
52+
:type endpoint: str
53+
:param resource_group_name: The name of the Resource Group. Required.
54+
:type resource_group_name: str
55+
:param subscription_id: The ID of the target subscription. Required.
56+
:type subscription_id: str
57+
:param workspace_name: The name of the Workspace. Required.
58+
:type workspace_name: str
59+
:param credential: Credential needed for the client to connect to Azure. Required.
60+
:type credential: ~azure.core.credentials.TokenCredential
61+
:keyword api_version: Api Version. Default value is "2022-11-01-preview". Note that overriding
62+
this default value may result in unsupported behavior.
63+
:paramtype api_version: str
64+
"""
65+
66+
def __init__(
67+
self,
68+
endpoint: str,
69+
resource_group_name: str,
70+
subscription_id: str,
71+
workspace_name: str,
72+
credential: "TokenCredential",
73+
**kwargs: Any
74+
) -> None:
75+
_endpoint = "https://{endpoint}"
76+
self._config = EasmClientConfiguration(
77+
endpoint=endpoint,
78+
resource_group_name=resource_group_name,
79+
subscription_id=subscription_id,
80+
workspace_name=workspace_name,
81+
credential=credential,
82+
**kwargs
83+
)
84+
self._client = PipelineClient(base_url=_endpoint, config=self._config, **kwargs)
85+
86+
self._serialize = Serializer()
87+
self._deserialize = Deserializer()
88+
self._serialize.client_side_validation = False
89+
self.assets = AssetsOperations(self._client, self._config, self._serialize, self._deserialize)
90+
self.discovery_groups = DiscoveryGroupsOperations(
91+
self._client, self._config, self._serialize, self._deserialize
92+
)
93+
self.discovery_templates = DiscoveryTemplatesOperations(
94+
self._client, self._config, self._serialize, self._deserialize
95+
)
96+
self.reports = ReportsOperations(self._client, self._config, self._serialize, self._deserialize)
97+
self.saved_filters = SavedFiltersOperations(self._client, self._config, self._serialize, self._deserialize)
98+
self.tasks = TasksOperations(self._client, self._config, self._serialize, self._deserialize)
99+
100+
def send_request(self, request: HttpRequest, **kwargs: Any) -> HttpResponse:
101+
"""Runs the network request through the client's chained policies.
102+
103+
>>> from azure.core.rest import HttpRequest
104+
>>> request = HttpRequest("GET", "https://www.example.org/")
105+
<HttpRequest [GET], url: 'https://www.example.org/'>
106+
>>> response = client.send_request(request)
107+
<HttpResponse: 200 OK>
108+
109+
For more information on this code flow, see https://aka.ms/azsdk/dpcodegen/python/send_request
110+
111+
:param request: The network request you want to make. Required.
112+
:type request: ~azure.core.rest.HttpRequest
113+
:keyword bool stream: Whether the response payload will be streamed. Defaults to False.
114+
:return: The response of your network call. Does not do error handling on your response.
115+
:rtype: ~azure.core.rest.HttpResponse
116+
"""
117+
118+
request_copy = deepcopy(request)
119+
path_format_arguments = {
120+
"endpoint": self._serialize.url("self._config.endpoint", self._config.endpoint, "str"),
121+
}
122+
123+
request_copy.url = self._client.format_url(request_copy.url, **path_format_arguments)
124+
return self._client.send_request(request_copy, **kwargs)
125+
126+
def close(self) -> None:
127+
self._client.close()
128+
129+
def __enter__(self) -> "EasmClient":
130+
self._client.__enter__()
131+
return self
132+
133+
def __exit__(self, *exc_details) -> None:
134+
self._client.__exit__(*exc_details)

0 commit comments

Comments
 (0)