Microsoft Defender for Endpoint

Collect logs from Microsoft Defender for Endpoint with Elastic Agent.

Version
2.25.0 (View all)
Compatible Kibana version(s)
8.13.0 or higher
Supported Serverless project types

Security
Observability
Subscription level
Basic
Level of support
Elastic

This integration is for Microsoft Defender for Endpoint logs.

Setting up

To allow the integration to ingest data from the Microsoft Defender API, you need to create a new application on your Azure domain. The procedure to create an application is found on the Create a new Azure Application documentation page.

Note: When giving the application the API permissions described in the documentation (Windows Defender ATP Alert.Read.All), it will only grant access to read alerts from ATP and nothing else in the Azure Domain

After the application has been created, it should contain 3 values that you need to apply to the module configuration.

These values are:

  • Client ID
  • Client Secret
  • Tenant ID

ECS mappings

Defender for Endpoint fieldsECS Fields
alertCreationTime
@timestamp
aadTenantId
cloud.account.id
category
threat.technique.name
computerDnsName
host.hostname
description
rule.description
detectionSource
observer.name
evidence.fileName
file.name
evidence.filePath
file.path
evidence.processId
process.pid
evidence.processCommandLine
process.command_line
evidence.processCreationTime
process.start
evidence.parentProcessId
process.parent.pid
evidence.parentProcessCreationTime
process.parent.start
evidence.sha1
file.hash.sha1
evidence.sha256
file.hash.sha256
evidence.url
url.full
firstEventTime
event.start
id
event.id
lastEventTime
event.end
machineId
cloud.instance.id
title
message
severity
event.severity

An example event for log looks as following:

{
    "@timestamp": "2023-09-22T03:31:55.887Z",
    "agent": {
        "ephemeral_id": "20bd2ad7-6c7e-4d34-9d55-57edc09ba1a6",
        "id": "a4d1a8b2-b45c-4d97-a37a-bd371f13111b",
        "name": "docker-fleet-agent",
        "type": "filebeat",
        "version": "8.8.1"
    },
    "cloud": {
        "account": {
            "id": "a839b112-1253-6432-9bf6-94542403f21c"
        },
        "instance": {
            "id": "111e6dd8c833c8a052ea231ec1b19adaf497b625"
        },
        "provider": "azure"
    },
    "data_stream": {
        "dataset": "microsoft_defender_endpoint.log",
        "namespace": "ep",
        "type": "logs"
    },
    "ecs": {
        "version": "8.11.0"
    },
    "elastic_agent": {
        "id": "a4d1a8b2-b45c-4d97-a37a-bd371f13111b",
        "snapshot": false,
        "version": "8.8.1"
    },
    "event": {
        "action": "Execution",
        "agent_id_status": "verified",
        "category": [
            "host"
        ],
        "created": "2021-01-26T20:33:57.7220239Z",
        "dataset": "microsoft_defender_endpoint.log",
        "duration": 101466100,
        "end": "2021-01-26T20:31:33.0577322Z",
        "id": "da637472900382838869_1364969609",
        "ingested": "2023-09-22T03:31:58Z",
        "kind": "alert",
        "provider": "defender_endpoint",
        "severity": 2,
        "start": "2021-01-26T20:31:32.9562661Z",
        "timezone": "UTC",
        "type": [
            "access",
            "start"
        ]
    },
    "host": {
        "hostname": "temp123.middleeast.corp.microsoft.com",
        "name": "temp123.middleeast.corp.microsoft.com"
    },
    "input": {
        "type": "httpjson"
    },
    "message": "Low-reputation arbitrary code executed by signed executable",
    "microsoft": {
        "defender_endpoint": {
            "evidence": {
                "aadUserId": "11118379-2a59-1111-ac3c-a51eb4a3c627",
                "accountName": "name",
                "domainName": "DOMAIN",
                "entityType": "User",
                "userPrincipalName": "temp123@microsoft.com"
            },
            "incidentId": "1126093",
            "investigationState": "Queued",
            "lastUpdateTime": "2021-01-26T20:33:59.2Z",
            "rbacGroupName": "A",
            "status": "New"
        }
    },
    "observer": {
        "name": "WindowsDefenderAtp",
        "product": "Defender for Endpoint",
        "vendor": "Microsoft"
    },
    "related": {
        "hosts": [
            "temp123.middleeast.corp.microsoft.com"
        ],
        "user": [
            "temp123"
        ]
    },
    "rule": {
        "description": "Binaries signed by Microsoft can be used to run low-reputation arbitrary code. This technique hides the execution of malicious code within a trusted process. As a result, the trusted process might exhibit suspicious behaviors, such as opening a listening port or connecting to a command-and-control (C&C) server."
    },
    "tags": [
        "microsoft-defender-endpoint",
        "forwarded"
    ],
    "threat": {
        "framework": "MITRE ATT&CK",
        "technique": {
            "name": [
                "Execution"
            ]
        }
    },
    "user": {
        "domain": "DOMAIN",
        "id": "S-1-5-21-11111607-1111760036-109187956-75141",
        "name": "temp123"
    }
}

Exported fields

FieldDescriptionType
@timestamp
Event timestamp.
date
cloud.image.id
Image ID for the cloud instance.
keyword
data_stream.dataset
Data stream dataset.
constant_keyword
data_stream.namespace
Data stream namespace.
constant_keyword
data_stream.type
Data stream type.
constant_keyword
event.dataset
Event dataset
constant_keyword
event.module
Event module
constant_keyword
host.containerized
If the host is a container.
boolean
host.os.build
OS build information.
keyword
host.os.codename
OS codename, if any.
keyword
input.type
Input type
keyword
log.offset
Log offset
long
microsoft.defender_endpoint.assignedTo
Owner of the alert.
keyword
microsoft.defender_endpoint.classification
Specification of the alert. Possible values are: 'Unknown', 'FalsePositive', 'TruePositive'.
keyword
microsoft.defender_endpoint.determination
Specifies the determination of the alert. Possible values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'.
keyword
microsoft.defender_endpoint.evidence.aadUserId
ID of the user involved in the alert
keyword
microsoft.defender_endpoint.evidence.accountName
Username of the user involved in the alert
keyword
microsoft.defender_endpoint.evidence.domainName
Domain name related to the alert
keyword
microsoft.defender_endpoint.evidence.entityType
The type of evidence
keyword
microsoft.defender_endpoint.evidence.ipAddress
IP address involved in the alert
ip
microsoft.defender_endpoint.evidence.userPrincipalName
Principal name of the user involved in the alert
keyword
microsoft.defender_endpoint.incidentId
The Incident ID of the Alert.
keyword
microsoft.defender_endpoint.investigationId
The Investigation ID related to the Alert.
keyword
microsoft.defender_endpoint.investigationState
The current state of the Investigation.
keyword
microsoft.defender_endpoint.lastUpdateTime
The date and time (in UTC) the alert was last updated.
date
microsoft.defender_endpoint.rbacGroupName
User group related to the alert
keyword
microsoft.defender_endpoint.resolvedTime
The date and time in which the status of the alert was changed to 'Resolved'.
date
microsoft.defender_endpoint.status
Specifies the current status of the alert. Possible values are: 'Unknown', 'New', 'InProgress' and 'Resolved'.
keyword
microsoft.defender_endpoint.threatFamilyName
Threat family.
keyword

Changelog

VersionDetailsKibana version(s)

2.25.0

Enhancement View pull request
Update the kibana constraint to ^8.13.0. Modified the field definitions to remove ECS fields made redundant by the ecs@mappings component template.

8.13.0 or higher

2.24.2

Bug fix View pull request
Fix bug handling message field when events are received from Logstash with ecs_compatibility turned on.

8.12.0 or higher

2.24.1

Bug fix View pull request
Fix handling of empty arrays.

8.12.0 or higher

2.24.0

Enhancement View pull request
Set sensitive values as secret.

8.12.0 or higher

2.23.3

Bug fix View pull request
Clean up null handling

8.7.1 or higher

2.23.2

Enhancement View pull request
Changed owners

8.7.1 or higher

2.23.1

Bug fix View pull request
Fix exclude_files pattern.

8.7.1 or higher

2.23.0

Enhancement View pull request
Limit request tracer log count to five.

8.7.1 or higher

2.22.0

Enhancement View pull request
ECS version updated to 8.11.0.

8.7.1 or higher

2.21.0

Enhancement View pull request
Improve 'event.original' check to avoid errors if set.

8.7.1 or higher

2.20.0

Enhancement View pull request
Update the package format_version to 3.0.0.

8.7.1 or higher

2.19.0

Enhancement View pull request
Update package to ECS 8.10.0 and align ECS categorization fields.

8.7.1 or higher

2.18.0

Enhancement View pull request
Add tags.yml file so that integration's dashboards and saved searches are tagged with "Security Solution" and displayed in the Security Solution UI.

8.7.1 or higher

2.17.0

Enhancement View pull request
Update package to ECS 8.9.0.

8.7.1 or higher

2.16.0

Enhancement View pull request
Update package-spec to 2.9.0.

8.7.1 or higher

2.15.0

Enhancement View pull request
Convert visualizations to lens.

8.7.1 or higher

2.14.0

Enhancement View pull request
Document valid duration units.

8.7.1 or higher

2.13.0

Enhancement View pull request
Ensure event.kind is correctly set for pipeline errors.

8.7.1 or higher

2.12.0

Enhancement View pull request
Update package to ECS 8.8.0.

8.7.1 or higher

2.11.0

Enhancement View pull request
Lowercase host.name field

8.7.1 or higher

2.10.0

Enhancement View pull request
Add a new flag to enable request tracing

8.7.1 or higher

2.9.0

Enhancement View pull request
Update package to ECS 8.7.0.

8.1.0 or higher

2.8.2

Enhancement View pull request
Added categories and/or subcategories.

8.1.0 or higher

2.8.1

Bug fix View pull request
Drop empty event sets.

8.1.0 or higher

2.8.0

Enhancement View pull request
Adding support for Oauth2 scopes that is required for some users

8.1.0 or higher

2.7.0

Enhancement View pull request
Update package to ECS 8.6.0.

8.1.0 or higher

2.6.0

Enhancement View pull request
Adds support for newer Oauth Token URL

8.1.0 or higher

2.5.2

Enhancement View pull request
Migrate the visualizations to by value in dashboards to minimize the saved object clutter and reduce time to load

8.1.0 or higher

2.5.1

Bug fix View pull request
Remove duplicate fields.

7.14.1 or higher
8.0.0 or higher

2.5.0

Enhancement View pull request
Update package to ECS 8.5.0.

7.14.1 or higher
8.0.0 or higher

2.4.0

Enhancement View pull request
Update package to ECS 8.4.0

7.14.1 or higher
8.0.0 or higher

2.3.1

Bug fix View pull request
Fix proxy URL documentation rendering.

7.14.1 or higher
8.0.0 or higher

2.3.0

Enhancement View pull request
Update package to ECS 8.3.0.

7.14.1 or higher
8.0.0 or higher

2.2.1

Enhancement View pull request
Update to Readme to include link to vendor documentation

7.14.1 or higher
8.0.0 or higher

2.2.0

Enhancement View pull request
Update to ECS 8.2

7.14.1 or higher
8.0.0 or higher

2.1.0

Enhancement View pull request
Add possibility to choose azure resource

7.14.1 or higher
8.0.0 or higher

2.0.1

Enhancement View pull request
Add documentation for multi-fields

7.14.1 or higher
8.0.0 or higher

2.0.0

Enhancement View pull request
Update to ECS 8.0

7.14.1 or higher
8.0.0 or higher

1.1.0

Enhancement View pull request
Add 8.0.0 version constraint

7.14.1 or higher
8.0.0 or higher

1.0.2

Enhancement View pull request
Update Title and Description.

7.14.1 or higher

1.0.1

Bug fix View pull request
Fix logic that checks for the 'forwarded' tag

1.0.0

Enhancement View pull request
First version

On this page