Enricher - Microsoft Defender Threat Intelligence

Note

This article describes how to configure a particular enrichment source. To see how to configure enrichers in general, see Configure enrichers.

	Specifications
Enricher name	Microsoft Defender Threat Intelligence (MDTI) See Individual enrichers
Observable types supported for enrichment	domain host ipv4 ipv6
API Base URL	https://graph.microsoft.com/v1.0/
Description	Enrichers here retrieves threat intelligence from Microsoft Defender Threat Intelligence to enrich a given ipv4, ipv6, domain, or host observable. For more information, see Individual enrichers

Requirements

Microsoft Graph is a protected resource that requires users to register an app, which this integration will use to authenticate with Microsoft Defender Threat Intelligence services.

For more information, see Microsoft Graph: Authentication and authorization basics.

Before you create the service application, you need:

• Your Microsoft Azure tenant ID.

• An active Defender Threat Intelligence Portal license and API add-on license for that tenant.

  For more information, see Microsoft Graph: Use the Microsoft Graph APIs for Microsoft Defender Threat Intelligence

• A Microsoft Azure user with at least the Cloud Application Administrator role.

  This user is required to Grant administrator consent to the app.

• A registered app.

  This provides you with a Client ID (Application (client) ID) and Client Secret (client secret value) for setting up this integration. See Register an app on Azure and assign permissions.

• Enable the Threat Intelligence Platform data connector in Microsoft Sentinel. For more information, see Microsoft documentation: https://learn.microsoft.com/en-us/azure/sentinel/connect-threat-intelligence-tip#enable-the-threat-intelligence-platforms-data-connector-in-microsoft-sentinel

Register an app on Azure and assign permissions

Before setting the enrichers, you must register an app on your Azure tenant.

Note

These instructions are based on: Microsoft Graph: Register an App to request authorization tokens and work with APIs

The instructions below are provided for your convenience.

To register an app and get credentials for this integration:

1. Sign in to the Azure portal.

2. Open the Active Directory Overview page in the Azure portal.

3. Select App registrations from the side bar.

4. Select New registration.

5. On the Register an application page, enter a Name for the application.

6. Select Register.

7. On the app’s overview page, save the following details in a safe location:

   • Application (client) ID.

   • Directory (tenant) ID

8. Then, create a secret. Select Certificates & secrets from the side bar.

9. In the Client secrets tab Select New client secret

10. Enter a Description and select Add.

11. Save the resulting client secret Value in a safe place.

Then, add ThreatIntelligence.Read.All permissions to your app.

1. Select API permissions from the side bar.

2. Select Add a permission.

3. Select Microsoft Graph.

4. Select Application permissions.

5. Under Select permissions, type ThreatIntelligence.

6. Select the ThreatIntelligence.Read.All permission.

7. Select Add permissions

You must ask an Azure administrator to Grant administrator consent for this app to use selected permissions.

Set up enrichers

Set up Individual enrichers before using them. In EclecticIQ Intelligence Center:

1. Go to Data configuration > Enrichers.

2. Select the enricher from the displayed list.

3. Edit the enricher by selecting from the top right More > Edit.

4. In the Edit enricher task view, fill out these fields:

   Note

   Required fields are marked with an asterisk (*).

   Field	Description
   API URL*	Default: https://graph.microsoft.com/api/v1.0
   Client ID*	Set this to your Application (client) ID.
   Client Secret*	Set this to your client secret value.
   Tenant ID*	Set the ID of the Azure tenant that your app is located on.
   SSL verification	Selected by default. Select to enable TLS for this integration.
   Path to SSL certificate file.	Used when connecting to a feed source that uses a custom CA. Set this as the path to the SSL certificate to use when authenticating the feed source. See SSL Certificates.

5. Click Save to store your changes.

SSL Certificates

To use an SSL certificate, it must be:

• Accessible on the EclecticIQ Intelligence Center host.

• Placed in a location that can be accessed by the eclecticiq user.

• Owned by eclecticiq:eclecticiq.

To make sure that EclecticIQ Intelligence Center can access the SSL certificate:

1. Upload the SSL certificate to a location on the EclecticIQ Intelligence Center host.

2. On the EclecticIQ Intelligence Center host, open the terminal.

3. Change ownership of the SSL certificate by running as root in the terminal:

   chown eclecticiq:eclecticiq /path/to/cert.pem
   

   Where /path/to/cert.pem is the location of the SSL certificate EclecticIQ Intelligence Center needs to access.

Individual enrichers

Microsoft Defender Threat Intelligence Whois Enricher

Gets whois record for enriched observable.

Supported observable kinds:

• ipv4

• ipv6

• domain

• host

Creates one indicator per enriched observable, with whois record details ingested as observables.

Mapping

See mapping

Caution

Actual implementation may differ.

class Address(Schema):
    ## ``countryOrRegion`` is not necessarily iso3166 value.
    # can be "US" (per docs) or "united states"
    countryOrRegion  ## --> MAP: COUNTRY
    city  ## --> MAP: CITY
    postalCode  ## --> MAP: POSTCODE
    street  ## --> MAP: STREET
    state ## --> Indicator label `state:{value}`

class Person(Schema):
    email  ## --> MAP: EMAIL
    name  ## --> MAP: NAME
    organization  ## --> MAP: ORGANIZATION
    telephone  ## --> MAP: TELEPHONE
    address  ## --> MAP: See Address()

## TOP LEVEL
class WhoIs(Schema):
    ## Map these nested classes
    abuse ## --> See Person()
    admin ## --> See Person()
    registrar ## --> See Person()
    registrant ## --> See Person()
    technical ## --> See Person()
    nameservers ## --> MAP: Union[IPV4, IPV6, HOST]
    host # Type: Union[IPV4, IPV6, HOST]

    # --> MAP: Indicator title
    # --> MAP: `{{https://graph.microsoft.com}}Indicator-{str(uuid5(NAMESPACE_X500, id))}`
    id

    expirationDateTime = fields.DateTime(allow_none=True)  ## --> MAP: Indicator threat_end_time
    registrationDateTime = fields.DateTime(allow_none=True)  ## --> MAP: Indicator label `registrationDateTime: {value}`
    firstSeenDateTime = fields.DateTime(allow_none=True)  ## --> MAP: Indicator threat_start_time
    lastSeenDateTime = fields.DateTime(allow_none=True)  ## --> MAP: Indicator observed_time
    lastUpdateDateTime = fields.DateTime(allow_none=True)  ## --> MAP: Indicator timestamp

    whoisServer  ## --> MAP: Indicator label `whoisServer: {value}`
    domainStatus  ## --> MAP: Indicator label `domainStatus: {value}`
    rawWhoisText  ## --> MAP: Indicator description
  

Microsoft Defender Threat Intelligence PassiveDNS Enricher

Gets Passive DNS record for enriched observable.

Supported observable kinds:

• ipv4

• ipv6

• domain

• host

Creates related observables per enriched observable.

Mapping

See mapping

Caution

Actual implementation may differ.

class ArtifactAny(Schema):
    # MAP
    # if odata_type == ODataType.IPAddress.value:
    #     id = fields.IP()  # MAP: Extracts, Union[IPV4, IPV6]
    # if odata_type == ODataType.HostName.value:
    #     id = fields.String()  # MAP: Extracts, Host
    id

class PassiveDNS(Schema):
    artifact

Microsoft Defender Threat Intelligence Host Enricher

Gets host records for enriched observable.

Note

For users migrating from Enricher - PassiveTotal IP/Domain, you may want to supplement output of this enricher with Microsoft Defender Threat Intelligence Host Pair Enricher and Microsoft Defender Threat Intelligence Subdomains Enricher.

Supported observable kinds:

• ipv4

• ipv6

• domain

• host

Creates related observables per enriched observable.

Mapping

See mapping

Caution

Actual implementation may differ.

class Host(Schema):
    # == MAP
    id = HostID  # MAP: Extract, Union[IPV4, IPV6, Host]
    countryOrRegion  # MAP: Extract, COUNTRY
    netblock  # MAP: Extract Union[IPV4_CIDR, IPV6_CIDR]
    autonomousSystem  # MAP: Extract, ASN.
    # Format: f"AS{str(value)}"
    registrar  # MAP: Extracts, REGISTRAR
    registrant  # MAP: Extracts, ORGANIZATION
    hostingProvider  # MAP: Extracts, ORGANIZATION

Microsoft Defender Threat Intelligence Host Pair Enricher

Gets Passive DNS record for enriched observable.

Supported observable kinds:

• ipv4

• ipv6

• domain

• host

Creates related observables per enriched observable.

Mapping

See mapping

Caution

Actual implementation may differ.

class HostPair(Schema):
    # == MAP
    # Deduplicate extracts from these fields
    parentHost  # MAP: Extract, Union[IPV4, IPV6, Host]
    childHost  # MAP: Extract, Union[IPV4, IPV6, Host]

Microsoft Defender Threat Intelligence Subdomains Enricher

Gets Passive DNS record for enriched observable.

Supported observable kinds:

• ipv4

• ipv6

• domain

• host

Creates related observables per enriched observable.

Mapping

See mapping

Caution

Actual implementation may differ.

class SubDomain(Schema):
    # == MAP
    host  # MAP: Extract, Union[IPV4, IPV6, Host]