Microsoft Graph Security (Preview)

The Microsoft Graph Security connector helps to connect different Microsoft and partner security products and services, using a unified schema, to streamline security operations, and improve threat protection, detection, and response capabilities. Learn more about integrating with the Microsoft Graph Security API at https://aka.ms/graphsecuritydocs

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
Flow Premium All Flow regions except the following:
     -   US Government (GCC)
PowerApps Premium All PowerApps regions except the following:
     -   US Government (GCC)

Prerequisites to connect with The Microsoft Graph Security connector

Read more about Microsoft Graph Security API.

  1. To use the Microsoft Graph Security connector action, start with a trigger, such as the Recurrence trigger.

  2. To use the Microsoft Graph Security connector, Azure Active Directory (AD) tenant administrator consent needs to be provided as part of Microsoft Graph Security Authentication requirements.

  3. The Microsoft Graph Security connector application ID and name (for Azure AD in https://portal.azure.com) is as follows for Azure AD administrator consent:

  • Application Name - MicrosoftGraphSecurityConnector
  • Application ID - c4829704-0edc-4c3d-a347-7c4a67586f3c
  1. Tenant administrator can either follow steps outlined in granting tenant administrator consent for Azure AD applications to the above mentioned application or can grant permissions upon initial run of a workflow using the Microsoft Graph Security connector per the application consent experience.

You are now ready to use the Microsoft Graph Security connector!

Throttling Limits

Name Calls Renewal Period
API calls per connection10060 seconds

Actions

Create subscriptions

Create Microsoft Graph webhook subscriptions.

Delete subscriptions

Delete the specific Microsoft Graph Webhook subscription.

Get active subscriptions

Get the list of unexpired subscriptions for this Azure Active Directory tenant.

Get alert by ID

Get a security alert corresponding to the specified ID.

Get alerts

Get a list of security alerts for this Azure Active Directory tenant. Use with different query parameters.

Update alert

Update specific properties of a security alert.

Update subscription

Renew a Microsoft Graph webhook subscription by updating its expiration time.

Create subscriptions

Create Microsoft Graph webhook subscriptions.

Parameters

Name Key Required Type Description
Resource URL
resource True string

Specify the resource that will be monitored for changes. Do not include base URL (https://graph.microsoft.com/v1.0/). Include security/alerts followed by the odata query. For e.g. security/alerts?$filter=status eq �New�

Change type
changeType True string

Specify the property type that should raise a notification when changed on the subscribed resource.

Client state
clientState string

Specify the client state to confirm the notification origination source.

Notification URL
notificationUrl True string

Specify a well-formed URL of the endpoint that will receive notifications.

Expiration date time
expirationDateTime True date-time

Specify the date time when the webhook subscription expires; needs to be a date time greater than current time and within 30 days.

Returns

A single subscription entity returned

Subscription
Subscription

Delete subscriptions

Delete the specific Microsoft Graph Webhook subscription.

Parameters

Name Key Required Type Description
Subscription ID
Subscription Id True string

Specify the Microsoft Graph Webhook Subscription ID.

Get active subscriptions

Get the list of unexpired subscriptions for this Azure Active Directory tenant.

Returns

Name Path Type Description
Existing subcriptions count
@odata.count integer

The number of subcriptions returned

Subscription
value array of Subscription

The subscription entities returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

Get alert by ID

Get a security alert corresponding to the specified ID.

Parameters

Name Key Required Type Description
Alert ID
alert-id True string

Specify alert ID.

Returns

A single alert entity returned

Alert
Alert

Get alerts

Get a list of security alerts for this Azure Active Directory tenant. Use with different query parameters.

Parameters

Name Key Required Type Description
Filter alerts
$filter string

Specify filtering condition for alerts like Severity eq "High".

Top alerts
$top integer

Specify the recent most top number of alerts to retrieve from each provider.

Select alert properties
$select string

Specify alert properties to include in the results.

Sorting order
$orderby string

Specify sorting order for the results.

Skips "n" results
$skip integer

Specify number of results to skip. Useful for pagination.

Include count of alerts returned
$count string

Specify to include the number of alerts returned in the response

Returns

Name Path Type Description
Alerts count
@odata.count integer

The number of alerts returned

Alerts
value array of Alert

The alerts returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

Update alert

Update specific properties of a security alert.

Parameters

Name Key Required Type Description
Alert ID
alert-id True string

Specify alert ID.

Assigned to
assignedTo string

Specify the name of the analyst the alert is assigned to for triage, investigation, or remediation.

Closed dateTime
closedDateTime string

Specify the time at which the alert was closed. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time.

Comments
comments string

Specify comments on alert for customer alert management.

Tags
Tags string

Specify alert ID.

Feedback
feedback string

Specify analyst feedback on the alert.

Status
status string

Specify status to track alert lifecycle status (stage).

Provider name
provider True string

Specific provider (product/service - not vendor company); for example, WindowsDefenderATP.

Provider version
providerVersion string

Specify version of the provider or subprovider, if it exists, that generated the alert.

Sub Provider name
subProvider string

Specific subprovider (under aggregating provider); for example, WindowsDefenderATP.SmartScreen.

Vendor name
vendor True string

Specify name of the alert vendor (for example, Microsoft, Dell, FireEye).

Update subscription

Renew a Microsoft Graph webhook subscription by updating its expiration time.

Parameters

Name Key Required Type Description
Subscription ID
Subscription Id True string

Specify Microsoft Graph Webhook subscription ID.

Expiration date time
expirationDateTime string

Specify the date and time, in UTC format, of when the Microsoft Graph webhook subscription expires. The maximum expiration time for security alerts is 43200 minutes (under 30 days).

Returns

A single subscription entity returned

Subscription
Subscription

Triggers

On all new alerts

Triggers on all new alerts

On new high severity alerts

Triggers on new high severity alerts

On all new alerts

Triggers on all new alerts

Returns

Name Path Type Description
Alerts count
@odata.count integer

The number of alerts returned

Alerts
value array of Alert

The alerts returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

On new high severity alerts

Triggers on new high severity alerts

Returns

Name Path Type Description
Alerts count
@odata.count integer

The number of alerts returned

Alerts
value array of Alert

The alerts returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

Definitions

Alert

A single alert entity returned

Name Path Type Description
Azure subscription ID
azureSubscriptionId string

Azure subscription ID, present if this alert is related to an Azure resource.

Tags
tags array of string

User-definable labels that can be applied to an alert and can serve as filter conditions (e.g. "HVA", "SAW", etc.).

ID
id string

Provider-generated GUID/unique identifier.

Azure tenant ID
azureTenantId string

Azure Active Directory tenant ID.

Activity group name
activityGroupName string

Name or alias of the activity group (attacker) this alert is attributed to.

Assigned to
assignedTo string

Name of the analyst the alert is assigned to for triage, investigation, or remediation.

Category
category string

Category of the alert (e.g. credentialTheft, ransomware, etc.).

Closed date time
closedDateTime date-time

Time at which the alert was closed (UTC).

Comments
comments array of string

Customer-provided comments on alert (for customer alert management).

Confidence
confidence integer

Confidence of the detection logic (percentage between 1-100).

Created date time
createdDateTime date-time

Time at which the alert was created (UTC).

Description
description string

Alert description.

Detection Ids
detectionIds array of string

Set of alerts related to this alert entity.

Event date time
eventDateTime date-time

Time at which the event(s) that served as the trigger(s) to generate the alert occurred (UTC).

Feedback
feedback string

Analyst feedback on the alert. Possible values are: unknown, truePositive, falsePositive, benignPositive.

Last modified date time
lastModifiedDateTime date-time

Time at which the alert entity was last modified (UTC).

Recommended actions
recommendedActions array of string

Vendor/Provider recommended action/s to take as a result of the alert (e.g. isolate machine, enforce2FA, reimage host, etc.).

Severity
severity string

Alert severity - set by vendor/provider. Values: (high, medium, low, Informational) where "informational" infers that the alert is not actionable.

Source materials
sourceMaterials array of string

Hyperlinks (URIs) to the source material related to the alert, e.g. provider investigation UI, etc.

Status
status string

Alert lifecycle status (stage). Values: (unknown, newAlert, inProgress, resolved).

Title
title string

Alert title.

Provider name
vendorInformation.provider string

Specific provider (product/service - not vendor company); for example, WindowsDefenderATP.

Provider version
vendorInformation.providerVersion string

Version of the provider or subprovider.

Sub provider name
vendorInformation.subProvider string

Specific subprovider (under aggregating provider); for example, WindowsDefenderATP.SmartScreen.

Vendor name
vendorInformation.vendor string

Name of the alert vendor (for example, Microsoft, Dell, FireEye).

Cloud app states
cloudAppStates array of object

Security-related stateful information generated by the provider about the cloud application/s related to this alert.

Destination service IP
cloudAppStates.destinationServiceIp string

Destination IP address of the connection to cloud app/service.

Destination service name
cloudAppStates.destinationServiceName string

Destination cloud app/service name.

Risk score
cloudAppStates.riskScore string

Provider-generated/calculated risk score of the Cloud Application/Service.

File states
fileStates array of object

Security-related stateful information generated by the provider about the file(s) related to this alert.

Name
fileStates.name string

File Name (without path).

Path
fileStates.path string

Full file path of the file/imageFile.

Risk score
fileStates.riskScore string

Provider generated/calculated risk score of the alert file.

Type
fileStates.fileHash.type string

File hash type. Possible values are: unknown, sha1, sha256, md5, authenticodeHash256, lsHash, ctph, peSha1, peSha256.

Value
fileStates.fileHash.value string

Value of the file hash.

Host states
hostStates array of object

Security-related stateful information generated by the provider about the host(s) related to this alert.

Fully qualified domain name
hostStates.fqdn string

Host FQDN (Fully Qualified Domain Name).

Is azureAd joined
hostStates.isAzureAdJoined boolean

True if the host is domain joined to Azure Active Directory Domain Services.

Is azureAd registered
hostStates.isAzureAdRegistered boolean

True if the host registered with Azure Active Directory Device Registration (e.g. BYOD) - not fully managed by enterprise.

Is hybrid azure domain joined
hostStates.isHybridAzureDomainJoined boolean

True if the host is domain joined to an on-premises Active Directory domain.

Net bios name
hostStates.netBiosName string

Local host name without DNS domain name.

Operating system name
hostStates.os string

Host Operating System.

Private IP address
hostStates.privateIpAddress string

Private (not routable) IPv4 or IPv6 Address at the time of the alert.

Public IP address
hostStates.publicIpAddress string

Publicly routable IPv4 or IPv6 Address at time of the alert.

Risk score
hostStates.riskScore string

Provider-generated/calculated risk score of the host.

Malware states
malwareStates array of object

Security-related stateful information generated by the provider about the malware related to this alert.

Category
malwareStates.category string

Provider-generated malware category (e.g. trojan, ransomware, etc.).

Family
malwareStates.family string

Provider-generated malware family (e.g. "wannacry", "notpetya", etc.).

Name
malwareStates.name string

Provider-generated malware variant name (e.g. Trojan:Win32/Powessere.H).

Severity
malwareStates.severity string

Provider-determined severity of this malware.

Was running
malwareStates.wasRunning boolean

Indicates whether the detected file (malware/vulnerability) was running at the time of detection or was detected at rest on the disk.

Network connections
networkConnections array of object

Security-related stateful information generated by the provider about the file(s) related to this alert.

Application name
networkConnections.applicationName string

Name of the application managing the network connection (e.g. Facebook, SMTP, etc.).

Destination address
networkConnections.destinationAddress string

Destination IP address of the network connection.

Destination domain
networkConnections.destinationDomain string

Destination domain portion of the destination URL.(for example "www.contoso.com").

Destination port
networkConnections.destinationPort string

Destination port of the network connection.

Destination url
networkConnections.destinationUrl string

Network connection URL/URI string - excluding parameters.

Direction
networkConnections.direction string

Network connection direction. Possible values are: unknown, inbound, outbound.

Domain registered dateTime
networkConnections.domainRegisteredDateTime date-time

Date the destination domain was registered (UTC).

Local dns name
networkConnections.localDnsName string

The local DNS name resolution as it appears in the host local DNS cache (e.g. in case the "hosts" file was tampered with).

Nat destination address
networkConnections.natDestinationAddress string

Network Address Translation destination IP address.

Nat destination port
networkConnections.natDestinationPort string

Network Address Translation destination port.

Nat source address
networkConnections.natSourceAddress string

Network Address Translation source IP address.

Nat source port
networkConnections.natSourcePort string

Network Address Translation source port.

Protocol
networkConnections.protocol string

Network protocol. Possible values are: unknown, ip, icmp, igmp, ggp, ipv4, tcp, pup, udp, idp, ipv6, ipv6RoutingHeader, ipv6FragmentHeader, ipSecEncapsulatingSecurityPayload, ipSecAuthenticationHeader, icmpV6, ipv6NoNextHeader, ipv6DestinationOptions, nd, raw, ipx, spx, spxII.

Risk score
networkConnections.riskScore string

Provider generated/calculated risk score of the network connection.

Source address
networkConnections.sourceAddress string

Source (i.e. origin) IP address of the network connection.

Source port
networkConnections.sourcePort string

Source (i.e. origin) IP port of the network connection.

Status
networkConnections.status string

Network connection status. Possible values are: unknown, attempted, succeeded, blocked, failed.

Url parameters
networkConnections.urlParameters string

Parameters (suffix) of the destination URL as a string.

Processes
processes array of object

Security-related stateful information generated by the provider about the process or processes related to this alert.

Account name
processes.accountName string

User account identifier (user account context the process ran under) e.g. AccountName, SID, etc.

Command line
processes.commandLine string

The full process invocation commandline including all parameters.

Created date time
processes.createdDateTime date-time

DateTime at which the parent process was started (UTC).

Integrity level
processes.integrityLevel string

The integrity level of the process. Possible values are: unknown, untrusted, low, medium, high, system.

Is elevated
processes.isElevated boolean

True if the process is elevated.

Name
processes.name string

The name of the process Image file.

Parent process created date time
processes.parentProcessCreatedDateTime date-time

Time at which the process was started (UTC).

Parent process ID
processes.parentProcessId integer

The Process ID (PID) of the parent process.

Parent process name
processes.parentProcessName string

The name of the image file of the parent process.

Path
processes.path string

Full path, including filename.

Process Id
processes.processId integer

The Process ID (PID) of the process.

Type
processes.fileHash.type string

File hash type. Possible values are: unknown, sha1, sha256, md5, authenticodeHash256, lsHash, ctph, peSha1, peSha256.

Value
processes.fileHash.value string

Value of the file hash.

Registry key states
registryKeyStates array of object

Security-related stateful information generated by the provider about the registry keys related to this alert.

Process
registryKeyStates.process string

Process ID (PID) of the process that modified the registry key (process details will appear in the alert "processes" collection).

Operation
registryKeyStates.operation string

Operation that changed the registry key name and/or value (add, modify, delete).

Value Type
registryKeyStates.valueType string

Registry key value type. Possible values are: unknown, binary, dword, dwordLittleEndian, dwordBigEndian, expandSz, link, multiSz, none, qword, qwordlittleEndian, sz.

Registry hive
registryKeyStates.hive string

Windows registry hive. Possible values are: unknown, currentConfig, currentUser, localMachineSam, localMachineSamSoftware, localMachineSystem, usersDefault.

Key
registryKeyStates.key string

Current (i.e. changed) registry key (excludes HIVE).

Value name
registryKeyStates.valueName string

Current (i.e. changed) registry key value name.

Value data
registryKeyStates.valueData string

Current (i.e. changed) registry key value data (contents).

Old key
registryKeyStates.oldKey string

Previous (i.e. before changed) registry key (excludes HIVE).

Old value name
registryKeyStates.oldValueName string

Previous (i.e. before changed) registry key value name.

Old value data
registryKeyStates.oldValueData string

Previous (i.e. before changed) registry key value data (contents).

Triggers
triggers array of object

Security-related information about the specific properties that triggered the alert (properties appearing in the alert). Alerts might contain information about multiple users, hosts, files, ip addresses. This field indicates which properties triggered the alert generation.

Name
triggers.name string

Name of the property serving as a detection trigger.

Type
triggers.type string

Type of the attribute in the key:value pair for interpretation, e.g. String, Boolean, etc.

Value
triggers.value string

Value of the attribute serving as a detection trigger.

User states
userStates array of object

Security-related stateful information generated by the provider about the logged-on user or users related to this alert.

AAD user ID
userStates.aadUserId string

AAD User object identifier (GUID) - represents the physical/multi-account user entity.

Account name
userStates.accountName string

Account name of user account (without Active Directory Domain or DNS Domain) - (also called "mailNickName").

Domain name
userStates.domainName string

NetBIOS/Active Directory Domain of user account �(i.e. domain\account format).

Email role
userStates.emailRole string

For email-related alerts - user account email role.

Is Vpn
userStates.isVpn boolean

Indicates whether the user logged on through a VPN.

Logon date time
userStates.logonDateTime date-time

Time at which the logon occurred (UTC).

Logon ID
userStates.logonId string

User sign-in ID.

Logon IP
userStates.logonIp string

IP Address the logon request orginated from.

Logon location
userStates.logonLocation string

Location (by IP address mapping) associated with a user sign-in event by this user.

Logon type
userStates.logonType string

Method of user sign in. Possible values are: unknown, interactive, remoteInteractive, network, batch, service.

On premises security identifier
userStates.onPremisesSecurityIdentifier string

Active Directory (on-premises) Security Identifier (SID) of the user.

Risk score
userStates.riskScore string

Provider-generated/calculated risk score of the user account.

User account type
userStates.userAccountType string

User account type (group membership), per Windows definition. Possible values are: unknown, standard, power, administrator.

User principal name
userStates.userPrincipalName string

User sign-in name - internet format: @.

Vulnerability states
vulnerabilityStates array of object

Threat intelligence pertaining to one or more vulnerabilities related to this alert.

Cve
vulnerabilityStates.cve string

Common Vulnerabilities and Exposures (CVE) for the vulnerability.

Was running
vulnerabilityStates.wasRunning boolean

Indicates whether the detected vulnerability (file) was running at the time of detection or was the file detected at rest on the disk.

Severity
vulnerabilityStates.severity string

Base Common Vulnerability Scoring System (CVSS) severity score for this vulnerability.

Subscription

A single subscription entity returned

Name Path Type Description
ID
id string

Unique identifier for the subscription.

Resource
resource string

Specifies the resource that will be monitored for changes.

Application Id
applicationId string

Identifier of the application used to create the subscription.

Change type
changeType string

Indicates the type of change in the subscribed resource that will raise a notification.

Client state
clientState string

Specifies the value of the clientState property sent by the service in each notification. The maximum length is 128 characters. The client can check that the notification came from the service by comparing the value of the clientState property sent with the subscription with the value of the clientState property received with each notification.

Notification URL
notificationUrl string

The URL of the endpoint that will receive the notifications. This URL must make use of the HTTPS protocol.

Expiration date time
expirationDateTime string

Specifies the date and time when the webhook subscription expires (UTC).

Creator Id
creatorId string

Identifier of the user or service principal that created the subscription. If the app used delegated permissions to create the subscription, this field contains the id of the signed-in user the app called on behalf of. If the app used application permissions, this field contains the id of the service principal corresponding to the app.