Microsoft Defender XDR
Architecture and deployment

Deploy content as code with ISOC in Microsoft Defender - Microsoft Defender XDR | Microsoft Learn

In brief

The documentation now describes repository connections that deploy content to ISOC or Microsoft Sentinel workspaces, or supported Defender content to Microsoft Defender XDR at tenant scope. Tenant targets support Defender workbooks and custom detections, and don't require a workspace.

What Defender admins need to know

Review deployment targets, supported content formats, and licensing prerequisites when planning CI/CD connections. No required administrator action is stated.

Summaries are generated from the documentation change itself.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Deploy content as code from your repository for anwith ISOC workspacein Microsoft Defender - Microsoft Defender XDR | Microsoft Learn

Use repositories with Integrated Security Operations Center (ISOC) in Microsoft Defender to manage and deploy custom security content to your ISOC workspace by using CI/CD.continuous integration and continuous delivery (CI/CD).

Repository connections support a target-based deployment model. Depending on your tenant configuration, you can deploy content to a workspace, either ISOC or Microsoft Sentinel, or deploy supported Defender-level content to Microsoft Defender XDR at tenant scope.

Workspace-targeted connections support existing workspace content types and supported Defender-level content. Tenant-targeted connections support Defender workbooks and custom detections.

You can manage content from the Microsoft Defender portal or ana supported external GitHub or Azure DevOpssource control repository. Managing contentUpdates made in an externalyour repository lets you update content outside of Microsoft Defender andare automatically deploy those updatesdeployed to your ISOC workspace.

The CI/CD experience and supported content types for an ISOC workspace are the same as the existing Microsoft Sentinel repository experience.

Note

This feature is in preview. Capabilities and availability might change during the preview period.selected target.

Prerequisites

Before you begin, make sure the following requirements are met:

  • Your tenant is eligible for ISOC.
  • YouFor workspace-targeted connections, you have an ISOC workspace or an existing Microsoft Sentinel workspace in a resource group where you have the Owner role. A workspace isn't required for tenant-targeted connections.
  • You have the Global Administrator role in Microsoft Entra ID for the initial CI/CD setup.
  • Custom content files that you want to deploy to your workspace are in a supported format.format for the selected deployment target. For supported formats, see Plan your repository content.
  • The account you use to create the connection is in your home tenant. External identities such as B2B guest accounts and delegated access aren't supported.
  • (Custom detection rules only)detections and Defender workbooks) You have a Microsoft 365 E5an ISOC-eligible license or an equivalent license that includes Microsoft Defender XDR. For more information, see Deploy custom detection rules as code.

GitHub prerequisites

  • You have Collaborator access to your GitHub repository.
  • GitHub Actions is enabled.

Azure DevOps prerequisites (workspace only)

Before connecting to Azure DevOps, make sure that:

For more information about deployable content types, see Plan your repository content.

Supported deployment targets and content types

When you create a repository connection, select the target where you want to deploy content.

Deployment targetSupported content
WorkspaceExisting supported Microsoft Sentinel workspace content, custom detections, and Defender workbooks
Defender XDRCustom detections and Defender workbooks

The available content types are filtered based on the selected deployment target and tenant eligibility.

Workspace-targeted connections

Use a workspace-targeted connection to deploy content to an ISOC workspace or an existing Microsoft Sentinel workspace.

Workspace-targeted connections support existing Microsoft Sentinel repository content types and Defender-level content.

Tenant-targeted connections

Use a Defender XDR target to deploy supported content at tenant scope.

Tenant-targeted connections support Defender workbooks and custom detections. An ISOC or Microsoft Sentinel workspace isn't required for this deployment target.

For eligible tenants without a workspace, Defender XDR is the only available deployment target.

Connect a repository

Use this procedure to connectcreate a GitHubrepository connection for a workspace or Azure DevOps repository toMicrosoft Defender XDR deployment target. The available targets depend on your ISOC workspace.tenant configuration.

Each connection can deploy the content types supported by its selected target. Workspace-targeted connections support multiple types of custom content,existing workspace content types, including analytics rules, automation rules, custom detection rules, hunting queries, parsers, playbooks, and workbooks. Tenant-targeted connections support Defender workbooks and custom detections.

For more information, see About Microsoft Sentinel content and solutions.

You can't create duplicate connections with the same repository and branch in a single ISOC workspace.

  1. Sign in to the Microsoft Defender portal.
  2. Make sure that you're signed in to your source control application with the credentials you want to use for the connection.
  3. In the Defender portal, selectMicrosoft Sentinel > Content management > Repositories.
  4. Select Add new.
  5. On the Create new deployment connection page, enter a name for the connection.
  6. Enter a description for the connection.
    1. In GitHub, select the repository where you want to install the Azure-Sentinel app.

    2. Install the Azure-Sentinel app.

    3. Return to the Create new deployment connection page.

    4. From Branch, select the branch that you want to connectconnect.

    5. From Target, select the deployment target:

      • Workspace to deploy content to an ISOC or Microsoft Sentinel workspace.
      • Defender XDR to deploy supported Defender-level content at tenant scope.

      If your tenant doesn't have an ISOC workspace.or Microsoft Sentinel workspace, only the Defender XDR target is available, provided your tenant is eligible for ISOC.

    6. From Content Types, select the types of content that you want to deploy. Available content types are filtered based on the selected target.

      Both parsers and hunting queries use the Saved Searches API to deploy content. If you select one of these content types and your branch contains the other type, both content types are deployed.

      For other content types, only the content types that you select are deployed.

    7. Select Create.

      For example:

      Screenshot of a new GitHub repository connection.

Azure DevOps (workspace only)

Azure DevOps automatically authorizes you by using your current Azure credentials.

1. Make sure that you're authorized to the same Azure DevOps tenant that you're connecting to from Microsoft Defender.

After you create the connection, a new workflow or pipeline is generated in your repository. TheSupported content stored infrom your repository is deployed to your ISOC workspace.the selected workspace or Defender XDR tenant-level target.

Deployment time might vary depending on the amount of content that you're deploying.

After deployment is complete:

  • TheWorkspace-level content storedappears in your repository appears on the corresponding Microsoft Sentinel pagesexperiences in the Defender portal.
  • Defender-level content appears in the corresponding Microsoft Defender experiences.
  • The connection details on the Repositories page show the deployment status, time of the last deployment, and a link to the deployment logs.

The Repositories page provides a unified view of repository deployment status for workspaces you have access to. You can review deployment status without selecting each workspace separately.

For example:

Delete content

Deleting content from your repository doesn't automatically delete it from your ISOC workspace.content previously deployed to the selected target.

To remove content that was deployed through a repository:

  1. Delete the content from your repository.
  2. Delete the corresponding deployed content from the relevant Microsoft Sentinel in theor Microsoft Defender portal.experience.

You can filter content by its source name to help identify content deployed from repositories.

Remove a repository connection

Removing a repository connection stops future content deployments. Content that was previouslydeployments to the selected target. Previously deployed content remains in your ISOC workspace.at its deployment target.

To use Bicep files, your repository connection must be newer than November 1, 2024. Remove and recreate an older connection to update it.

To remove a repository connection:

  1. Sign in to the Microsoft Defender portal.
  2. Select Microsoft Sentinel > Content management > Repositories.
  3. Select the connection that you want to remove.
  4. Select Delete.
  5. Select Yes to confirm the deletion.

After you remove the connection, content previously deployed through the connectioncontent remains in your ISOC workspace.the corresponding workspace or Microsoft Defender experience. Content added to the repository after you remove the connection isn't deployed.

If you encounter an error when removing a connection, check your source control repository and confirm that the associated GitHub workflow or Azure DevOps pipeline is deleted.