​
Getting Started

​
How our integration works

We use Microsoft’s OAuth support for you to authorize Wirespeed to access your Microsoft tenant, collect a daily inventory of your licensed Microsoft products, and begin syncing your directory data (users and endpoints) and security telemetry. If you license a new Microsoft product today or 3 years from now, we’ll notice, pull the telemetry, and begin triaging detections on your behalf.

For details about the required permissions to do this work, read the Permission Details section below.

​
Integrating

To get started, add a new integration and select Microsoft. You will be redirected to the OAuth Consent Page.

​
Testing

​
Microsoft Defender for Endpoint

Running any of the below commands will trigger a detection for Microsoft Defender for Endpoint and will be ingested by Wirespeed. They will automatically be identified as test events by Wirespeed.

​
Microsoft Entra ID Protect

Depending on your licensing level, additional tests are available as well.

​
Errors

​
AADSTS650052

AADSTS650052: The app is trying to access a service ‘fc780465-2017-40d4-a0c5-307022471b92’(WindowsDefenderATP) that your organization ‘[ORGANIZATION_ID]’ lacks a service principal for. Contact your IT Admin to review the configuration of your service subscriptions or consent to the application in order to create the required service principal.
This error means you have not purchased Microsoft Defender for Endpoint. If you would like to proceed without purchasing, you need to add a placeholder service account, so that Microsoft will allow the integration to continue. The placeholder service account is associated with application id fc780465-2017-40d4-a0c5-307022471b92 which is a built-in Microsoft application for Defender for Endpoint. You may use methods A or B below to fix this issue:

​
A. Microsoft Graph Explorer

  1. As a global administrator, navigate to Microsoft Graph Explorer
  2. In the top right, make sure the Tenant shown is the one you want to integrate with. Otherwise select your profile icon next to that field and change accounts.
  3. Select Modify Permissions and consent to both required permissions
    1. If the permissions do not show up, manually select Application.ReadWrite.All and Directory.ReadWrite.All
  4. Click run query

Make sure you receive a 201 Created response. Then retry the integration setup from Wirespeed.

​
B. Microsoft Graph Command-Line

$> mgc service-principals create --body '"{\"appId\": \"fc780465-2017-40d4-a0c5-307022471b92\"}"'

​
Permission Details

We need a variety of permissions to integrate with your Microsoft tenant. The permissions manifest during the oAuth challenge can appear daunting or even unnecessary; we understand, which is why we only request permissions we need to deliver the best experience for you.

​
Read Access

  • The majority of the listed permissions in the oAuth dialog are read only. Microsoft requires us to request them individually, so the list seems long. At a high level, we need to read:
  • Security Alerts, obviously, because we need to triage these
  • IOCs (indicators of compromise), because these are a form of detection
  • Audit Log data, where important supplementary security telemetry lives
  • Sign in logs and data, so we can perform detections and analysis
  • Organization Information, which is metadata about your tenant itself, so we can ensure we are properly covering all of your organization’s security telemetry
  • Directory data, so we can learn your organization, your people, their roles, and how to best triage cases or interact with them.
  • Users’ profiles and authentication methods, so we can determine proper guidance for a security detection
  • File profiles, for enriching files referenced in detections
  • URL profiles, for enriching URLs referenced in detections
  • Risk detection and information, because posture related information informs and correlates with detections
  • Threat & Vulnerability management information, which informs and enriches detections
  • Security Baseline Assessment data, which informs and enriches detections
  • Remediation tasks, so we can know what tasks you completed and make better recommendations

​
Write Access

There are a handful of write permissions that we request, so that we can enable the best outcomes and experience for you. All of these are requested at the time of integration, but that does NOT mean they will be used until you opt into configuration settings that leverage these permissions. However, it’s a better user experience to request these permissions once, even if you don’t enable them within our platform. By default, these are blocked when your tenant is first created in test mode.

  • Risk detections, so we can update statuses (e.g. close resolved instances or false positives)
  • Security Alerts, so we can update statuses of the “ticket” portion of alerts and keep them in sync with our triage and response results
  • Users’ authentication methods, so we can update MFA policies for compromised accounts as a remediation step [Roadmap Feature, which will require opt-in within our platform]
  • Timeline events, so we can sync our case triage timelines with the timelines in the tickets of your detections within your Microsoft console
  • All machine information, so we can add comments and metadata to machines for your administrators to see as part of response

​
Containment Access

Lastly, there are a small set of permissions that we request, so that we can properly contain threats on your behalf, whether automated (if you opt-in and enable it), or manually (i.e. you click the contain button within our application to initiate a containment process). Just like the Write Access permissions above, none of these are enabled in our platform by default, and test mode is a total block that prevents these permissions from being used.

  • Enable/Disable user accounts, so that we can contain a compromised identity during a case, whether automated through user containment options or manually by clicking the contain button within our platform. The result is the Microsoft user account is disabled or enabled; this action is completely safe and reversible, either in-platform through the contain button, or directly in your preferred Microsoft user management tools.
  • Revoke all sign in sessions; in the case of an identity compromise, an unauthorized threat actor can persist with the access of your compromised user, even after the user’s credentials have been reset, by leveraging long-lasting sign in session tokens & cookies. This allows us to revoke all sign-ins, which kills threat actors’ access to user accounts. This is a safe and largely reversible action, i.e. the affected user can simply authenticate again to establish new sessions. At most, this is a minor inconvenience to users, in exchange for swift and complete containment of a hostile threat actor bent on reaching a malicious objective, like BEC or ransomware.
  • Run live response on a specific machine; this allows us the ability to perform additional telemetry collection, threat hunts, and thorough response actions by checking for a threat actor’s possible persistence on an endpoint in your fleet.
  • Restrict code execution; this grants us the ability to instruct Microsoft Defender for Endpoint (DFE) to take actions to block malicious code that DFE detected, but did not block, within your environment by establishing a rule to prevent its execution, following our endpoint containment configuration options after we’ve confirmed the code is hostile.
  • Stop and quarantine file; this allows us to to instruct Microsoft Defender for Endpoint (DFE) to stop a malicious process and quarantine the malicious files associated with it, when DFE only detects, but does not outright block the threat, following our endpoint containment configuration options after we have confirmed the suspected threat is in fact malicious.

​
Limiting Permissions

If, after reading and understanding the above about how and why the permissions are required, you would still like to reduce the permissions farther, you can:

  • Complete the oAuth dialog for the Microsoft integration to Wirespeed, accepting the permission list as presented.
  • Go to Azure > Enterprise Applications > Wirespeed and remove individual permissions (e.g. write or containment access) as a hard stop beyond the layers of controls present in Wirespeed.
  • Document the removed permissions, so that you can re-enable them manually, should you want to enable write/containment access later. Wirespeed will report errors when attempting certain functions, but it may not be readily apparent to us that the cause for the error is manually edited permissions.
  • Alternatively, you can choose to update the Microsoft integration later, accepting all of the permissions. You can do this in Wirespeed by going to Integrations > Add Integration > Microsoft and following the same process you did originally, without removing the permissions afterwards. This will update your permissions and retain your existing Microsoft data.