Microsoft Graph Security (Preview)

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 Standard All Flow regions except the following:
     -   US Government (GCC)
PowerApps Standard 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 connection 100 60 seconds

Actions

Create subscriptions

Create Microsoft Graph webhook subscriptions.

Required Parameters

Resource URL
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
string
Specify the property type that should raise a notification when changed on the subscribed resource.
Notification URL
string
Specify a well-formed URL of the endpoint that will receive notifications.
Expiration date time
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.

Optional Parameters

Client state
string
Specify the client state to confirm the notification origination source.

Returns

Subscription
Subscription

A single subscription entity returned

Delete subscriptions

Delete the specific Microsoft Graph Webhook subscription.

Required Parameters

Subscription ID
string
Specify the Microsoft Graph Webhook Subscription ID.

Returns

Subscription
Subscription

A single subscription entity returned

Get active subscriptions

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

Required Parameters

Resource URL
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
string
Specify the property type that should raise a notification when changed on the subscribed resource.
Notification URL
string
Specify a well-formed URL of the endpoint that will receive notifications.
Expiration date time
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.

Optional Parameters

Client state
string
Specify the client state to confirm the notification origination source.

Returns

Existing subcriptions count
integer
The number of subcriptions returned
Subscription
array of Subscription
The subscription entities returned
Next link
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.

Required Parameters

Alert ID
string
Specify alert ID.

Returns

Alert
Alert

A single alert entity returned

Get alerts

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

Optional Parameters

Filter alerts
string
Specify filtering condition for alerts like Severity eq "High".
Top alerts
integer
Specify the recent most top number of alerts to retrieve from each provider.
Select alert properties
string
Specify alert properties to include in the results.
Sorting order
string
Specify sorting order for the results.
Skips "n" results
integer
Specify number of results to skip. Useful for pagination.
Include count of alerts returned
string
Specify to include the number of alerts returned in the response

Returns

Alerts count
integer
The number of alerts returned
Alerts
array of Alert
The alerts returned
Next link
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.

Required Parameters

Alert ID
string
Specify alert ID.
Provider name
string
Specific provider (product/service - not vendor company); for example, WindowsDefenderATP.
Vendor name
string
Specify name of the alert vendor (for example, Microsoft, Dell, FireEye).

Optional Parameters

Assigned to
string
Specify the name of the analyst the alert is assigned to for triage, investigation, or remediation.
Closed dateTime
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
string
Specify comments on alert for customer alert management.
Tags
string
Feedback
string
Specify analyst feedback on the alert.
Status
string
Specify status to track alert lifecycle status (stage).
Provider version
string
Specify version of the provider or subprovider, if it exists, that generated the alert.
Sub Provider name
string
Specific subprovider (under aggregating provider); for example, WindowsDefenderATP.SmartScreen.

Returns

Subscription
Subscription

A single subscription entity returned

Update subscription

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

Required Parameters

Subscription ID
string
Specify Microsoft Graph Webhook subscription ID.

Optional Parameters

Expiration date time
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

Subscription
Subscription

A single subscription entity returned

Definitions

Alert

A single alert entity returned

AAD user ID
string
AAD User object identifier (GUID) - represents the physical/multi-account user entity.
Account name
string
Account name of user account (without Active Directory Domain or DNS Domain) - (also called "mailNickName").
Account name
string
User account identifier (user account context the process ran under) e.g. AccountName, SID, etc.
Activity group name
string
Name or alias of the activity group (attacker) this alert is attributed to.
Application name
string
Name of the application managing the network connection (e.g. Facebook, SMTP, etc.).
Assigned to
string
Name of the analyst the alert is assigned to for triage, investigation, or remediation.
Azure subscription ID
string
Azure subscription ID, present if this alert is related to an Azure resource.
Azure tenant ID
string
Azure Active Directory tenant ID.
Category
string
Category of the alert (e.g. credentialTheft, ransomware, etc.).
Category
string
Provider-generated malware category (e.g. trojan, ransomware, etc.).
Closed date time
date-time
Time at which the alert was closed (UTC).
Cloud app states
array of object
Security-related stateful information generated by the provider about the cloud application/s related to this alert.
Command line
string
The full process invocation commandline including all parameters.
Comments
array of string
Customer-provided comments on alert (for customer alert management).
Confidence
integer
Confidence of the detection logic (percentage between 1-100).
Created date time
date-time
Time at which the alert was created (UTC).
Created date time
date-time
DateTime at which the parent process was started (UTC).
Cve
string
Common Vulnerabilities and Exposures (CVE) for the vulnerability.
Description
string
Alert description.
Destination address
string
Destination IP address of the network connection.
Destination domain
string
Destination domain portion of the destination URL.(for example "www.contoso.com").
Destination port
string
Destination port of the network connection.
Destination service IP
string
Destination IP address of the connection to cloud app/service.
Destination service name
string
Destination cloud app/service name.
Destination url
string
Network connection URL/URI string - excluding parameters.
Detection Ids
array of string
Set of alerts related to this alert entity.
Direction
string
Network connection direction. Possible values are: unknown, inbound, outbound.
Domain name
string
NetBIOS/Active Directory Domain of user account �(i.e. domain\account format).
Domain registered dateTime
date-time
Date the destination domain was registered (UTC).
Email role
string
For email-related alerts - user account email role.
Event date time
date-time
Time at which the event(s) that served as the trigger(s) to generate the alert occurred (UTC).
Family
string
Provider-generated malware family (e.g. "wannacry", "notpetya", etc.).
Feedback
string
Analyst feedback on the alert. Possible values are: unknown, truePositive, falsePositive, benignPositive.
File states
array of object
Security-related stateful information generated by the provider about the file(s) related to this alert.
Fully qualified domain name
string
Host FQDN (Fully Qualified Domain Name).
Host states
array of object
Security-related stateful information generated by the provider about the host(s) related to this alert.
ID
string
Provider-generated GUID/unique identifier.
Integrity level
string
The integrity level of the process. Possible values are: unknown, untrusted, low, medium, high, system.
Is Vpn
boolean
Indicates whether the user logged on through a VPN.
Is azureAd joined
boolean
True if the host is domain joined to Azure Active Directory Domain Services.
Is azureAd registered
boolean
True if the host registered with Azure Active Directory Device Registration (e.g. BYOD) - not fully managed by enterprise.
Is elevated
boolean
True if the process is elevated.
Is hybrid azure domain joined
boolean
True if the host is domain joined to an on-premises Active Directory domain.
Key
string
Current (i.e. changed) registry key (excludes HIVE).
Last modified date time
date-time
Time at which the alert entity was last modified (UTC).
Local dns name
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).
Logon ID
string
User sign-in ID.
Logon IP
string
IP Address the logon request orginated from.
Logon date time
date-time
Time at which the logon occurred (UTC).
Logon location
string
Location (by IP address mapping) associated with a user sign-in event by this user.
Logon type
string
Method of user sign in. Possible values are: unknown, interactive, remoteInteractive, network, batch, service.
Malware states
array of object
Security-related stateful information generated by the provider about the malware related to this alert.
Name
string
Provider-generated malware variant name (e.g. Trojan:Win32/Powessere.H).
Name
string
The name of the process Image file.
Name
string
File Name (without path).
Name
string
Name of the property serving as a detection trigger.
Nat destination address
string
Network Address Translation destination IP address.
Nat destination port
string
Network Address Translation destination port.
Nat source address
string
Network Address Translation source IP address.
Nat source port
string
Network Address Translation source port.
Net bios name
string
Local host name without DNS domain name.
Network connections
array of object
Security-related stateful information generated by the provider about the file(s) related to this alert.
Old key
string
Previous (i.e. before changed) registry key (excludes HIVE).
Old value data
string
Previous (i.e. before changed) registry key value data (contents).
Old value name
string
Previous (i.e. before changed) registry key value name.
On premises security identifier
string
Active Directory (on-premises) Security Identifier (SID) of the user.
Operating system name
string
Host Operating System.
Operation
string
Operation that changed the registry key name and/or value (add, modify, delete).
Parent process ID
integer
The Process ID (PID) of the parent process.
Parent process created date time
date-time
Time at which the process was started (UTC).
Parent process name
string
The name of the image file of the parent process.
Path
string
Full file path of the file/imageFile.
Path
string
Full path, including filename.
Private IP address
string
Private (not routable) IPv4 or IPv6 Address at the time of the alert.
Process
string
Process ID (PID) of the process that modified the registry key (process details will appear in the alert "processes" collection).
Process Id
integer
The Process ID (PID) of the process.
Processes
array of object
Security-related stateful information generated by the provider about the process or processes related to this alert.
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.
Provider name
string
Specific provider (product/service - not vendor company); for example, WindowsDefenderATP.
Provider version
string
Version of the provider or subprovider.
Public IP address
string
Publicly routable IPv4 or IPv6 Address at time of the alert.
Recommended actions
array of string
Vendor/Provider recommended action/s to take as a result of the alert (e.g. isolate machine, enforce2FA, reimage host, etc.).
Registry hive
string
Windows registry hive. Possible values are: unknown, currentConfig, currentUser, localMachineSam, localMachineSamSoftware, localMachineSystem, usersDefault.
Registry key states
array of object
Security-related stateful information generated by the provider about the registry keys related to this alert.
Risk score
string
Provider-generated/calculated risk score of the user account.
Risk score
string
Provider-generated/calculated risk score of the host.
Risk score
string
Provider generated/calculated risk score of the alert file.
Risk score
string
Provider-generated/calculated risk score of the Cloud Application/Service.
Risk score
string
Provider generated/calculated risk score of the network connection.
Severity
string
Provider-determined severity of this malware.
Severity
string
Base Common Vulnerability Scoring System (CVSS) severity score for this vulnerability.
Severity
string
Alert severity - set by vendor/provider. Values: (high, medium, low, Informational) where "informational" infers that the alert is not actionable.
Source address
string
Source (i.e. origin) IP address of the network connection.
Source materials
array of string
Hyperlinks (URIs) to the source material related to the alert, e.g. provider investigation UI, etc.
Source port
string
Source (i.e. origin) IP port of the network connection.
Status
string
Alert lifecycle status (stage). Values: (unknown, newAlert, inProgress, resolved).
Status
string
Network connection status. Possible values are: unknown, attempted, succeeded, blocked, failed.
Sub provider name
string
Specific subprovider (under aggregating provider); for example, WindowsDefenderATP.SmartScreen.
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.).
Title
string
Alert title.
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.
Type
string
Type of the attribute in the key:value pair for interpretation, e.g. String, Boolean, etc.
Type
string
File hash type. Possible values are: unknown, sha1, sha256, md5, authenticodeHash256, lsHash, ctph, peSha1, peSha256.
Type
string
File hash type. Possible values are: unknown, sha1, sha256, md5, authenticodeHash256, lsHash, ctph, peSha1, peSha256.
Url parameters
string
Parameters (suffix) of the destination URL as a string.
User account type
string
User account type (group membership), per Windows definition. Possible values are: unknown, standard, power, administrator.
User principal name
string
User sign-in name - internet format: <user account name>@<user account DNS domain name>.
User states
array of object
Security-related stateful information generated by the provider about the logged-on user or users related to this alert.
Value
string
Value of the file hash.
Value
string
Value of the file hash.
Value
string
Value of the attribute serving as a detection trigger.
Value Type
string
Registry key value type. Possible values are: unknown, binary, dword, dwordLittleEndian, dwordBigEndian, expandSz, link, multiSz, none, qword, qwordlittleEndian, sz.
Value data
string
Current (i.e. changed) registry key value data (contents).
Value name
string
Current (i.e. changed) registry key value name.
Vendor name
string
Name of the alert vendor (for example, Microsoft, Dell, FireEye).
Vulnerability states
array of object
Threat intelligence pertaining to one or more vulnerabilities related to this alert.
Was running
boolean
Indicates whether the detected vulnerability (file) was running at the time of detection or was the file detected at rest on the disk.
Was running
boolean
Indicates whether the detected file (malware/vulnerability) was running at the time of detection or was detected at rest on the disk.

Subscription

A single subscription entity returned

Application Id
string
Identifier of the application used to create the subscription.
Change type
string
Indicates the type of change in the subscribed resource that will raise a notification.
Client state
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.
Creator Id
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.
Expiration date time
string
Specifies the date and time when the webhook subscription expires (UTC).
ID
string
Unique identifier for the subscription.
Notification URL
string
The URL of the endpoint that will receive the notifications. This URL must make use of the HTTPS protocol.
Resource
string
Specifies the resource that will be monitored for changes.