Microsoft Graph API Threat Intelligence

The Microsoft Graph API Threat Intelligence connector facilitates the automation of threat detection and response by integrating with Microsoft's security intelligence ecosystem.

Microsoft Graph API Threat Intelligence is a comprehensive platform for security analysis and threat detection. It enables users to retrieve detailed insights, analyze threat assessments, and manage Threat Intelligence indicators within Microsoft Graph Security API. By integrating with Swimlane Turbine, security teams can automate the ingestion and analysis of threat data, enhance security posture, and respond to incidents more efficiently, leveraging the vast intelligence capabilities of Microsoft Graph API without the need for manual coding.

Configuration

Prerequisites

To effectively utilize the Microsoft Graph API Threat Intelligence connector, ensure you have the following prerequisites:

Client Credentials and Tenant ID authentication with these parameters:

URL: Endpoint for Microsoft Graph API

Client ID: Application ID registered in Azure AD

Client Secret: Key generated for the application in Azure AD

Tenant ID: Directory ID of the Azure AD tenant

Scope: Permissions required for the API access

OAuth 2.0 Client Credentials with these parameters:

URL: Endpoint for Microsoft Graph API

Client ID: Application ID registered in Azure AD

Client Secret: Key generated for the application in Azure AD

Token URL: URL to retrieve the OAuth token

Scope: Permissions required for the API access

Delegated Flow Authentication with these parameters:

URL: Endpoint for Microsoft Graph API

Tenant ID: Directory ID of the Azure AD tenant ... and so on

Authentication Methods

OAuth 2.0 client credentials authentication with these parameters:

url: Endpoint for Microsoft Graph API.

client_id: Application (client) ID registered in Azure AD.

client_secret: Client secret (key) generated for the application in Azure AD.

token_url: URL to retrieve the OAuth token.

scope: Permissions the app requires.

Password Grant (Delegated Authentication) for acting on behalf of a user:

url: Endpoint for Microsoft Graph API.

tenant_id: Directory ID of the Azure AD tenant.

oauth_un: User's username to authenticate.

oauth_pwd: User's password to authenticate.

oauth_cl_id: Application (client) ID registered in Azure AD.

oauth_cl_secret: Client secret (key) generated for the application in Azure AD.

login_url: Login URL. Default value is https://login.microsoftonline.com. (Optional).

scope: Permissions the app requires. Optional field. (Optional).

Asset credentials specific to your organization (Microsoft Graph API Asset - Tenant ID):

url: Endpoint for Microsoft Graph API.

client_ID: Application (client) ID registered in Azure AD.

client_Secret: Client secret (key) generated for the application in Azure AD.

tenant_id: Directory ID of the Azure AD tenant.

scope: Permissions the app requires.

Authentication for OAuth2 Refresh Token Grant credentials for Microsoft Graph API authentication

url: Endpoint for Microsoft Graph API.

client_ID: Application (client) ID registered in Azure AD.

client_Secret: Client secret (key) generated for the application in Azure AD.

refresh_token: Refresh Token.

scope: Permissions the app requires.

Capabilities

The Microsoft Graph API connector gives the ability to get and update security alerts, and modify user licenses and sessions.

Create Threat Intel Indicator Microsoft Defender

Create Threat Intel Indicator Azure Sentinel

Delete Threat Intelligence Indicator

Get Threat Assessment

Get Threat Assessment List

Get Threat Intelligence Indicator

Get Threat Intelligence Indicators List

Post Threat Assessment Email

Post Threat Assessment File

Post Threat Assessment URI

Post Threat Assessment URL

Asset Setup

Client Credential Flow Authentication

Authentication uses Azure application OAuth2. You will need an admin account in Azure to create the application.

Recommended Application Permissions (feel free use custom permissions if you only use certain actions):

User.ReadWrite.All

Calendars.ReadWrite

Directory.ReadWrite.All

Directory.AccessAsUser.All

SecurityEvents.Read.All

SecurityEvents.ReadWrite.All

AuditLog.Read.All

Mail.ReadBasic.All

SecurityAnalyzedMessage.ReadWrite.All

SecurityAlert.ReadWrite.All

User.ReadWrite.All

SecurityIncident.ReadWrite.All

IdentityRiskyUser.Read.All

In order to set up the asset, you need the following:

Azure Application Client ID

Azure Application Client Secret

Azure Tenant ID

Steps to create the Azure app:

Go to the App Registration page in the Azure portal.

Click New Registration.

Enter a name for your new application and choose Accounts in this organizational directory only, then click Register at the bottom.

Navigate to the API permissions tab on the left navigation menu.

Select Add a permission.

Select Microsoft Graph.

Select Application permissions, then mark all the permissions you need for the actions you are using (See suggested permissions at the top of the asset setup section).

Click the Add permissions button at the bottom of the page.

Select Grant admin consent for your organization, then your permissions should look as below.

Navigate to the Certificates & secrets tab and select New client secret.

Fill out the description and expiration, then click the Add button at the bottom.

The Value of the secret you just created is the Client Secret needed for the Swimlane asset.

Navigate to the Overview tab on the left menu.

The Client ID and Tenant ID needed in the asset are shown on this page.

The Client ID, Tenant ID, and Client Secret described in the steps above are the credentials you need for the asset.

Password Flow (Delegated Auth)

Use Delegated Permissions, instead of Application Permissions, and generate Client ID, Tenant ID, and Client Secret as described in the above Client Credential Flow Authentication.

We also need an Username and a Password for this authentication.

Authentication flow for OAuth2 Refresh Token

Oauth 2.0 refresh token grant, which requires a Refresh Token,Tenant ID, Client ID and Client Secret. Use this auth with accounts which have MFA enabled. To generate a refresh token please follow the instructions below.

In step 3 of the above-mentioned setup instructions, please provide a Redirect URI and select the platform as 'Web', before clicking on Register at the the bottom.

Proceed with the remaining steps to generate 'Client ID', Tenant ID and Client Secret.

Add the permissions in Delegated Permissions.

The Swimlane team will provide a Python script and instructions on how to use the script to generate the Refresh Token.

Limit Access to specific mailboxes

Administrators who want to limit app access to specific mailboxes can create an application access policy by using the New-ApplicationAccessPolicy PowerShell cmdlet. For more information please see the article Limiting application permissions to specific Exchange Online mailboxes.

Action Setup

OData filters

Information on the filter input formatting can be found here.

Keep in mind that not specifying a folder as an input will result in the query affecting all possible folders. Example: If we want to ingest only unread emails, and we don't set the input "folder", we will ingest all unread emails from all folders, including "Deleted Items", "Junk", etc.

Well Known Folders

Well known folders can be used instead of Folder IDs for email actions. All well known folder names can be found here.

Sites Get Site

All the Sites actions require the site ID to be executed. The site ID can be obtained using the action Sites Get Site, in order to run the action the site_hostname and site_name are needed. This two values can be found in a site URL:

https://{site_hostname}.sharepoint.com/sites/{site_name}

For example if our site URL is https://swimlaneintegrations.sharepoint.com/sites/IntegrationsSite we should use:

site_hostname: swimlaneintegrations

site_name: IntegrationsSite

After the action execution you can find the Site ID on the ID output field.

Sites Create List

In order to create a list with its columns, use the input Columns. You can find all the possible values with its configuration on the following table.

Property name	Type	Description
boolean	booleanColumn	This column stores boolean values.
calculated	calculatedColumn	This column's data is calculated based on other columns.
choice	choiceColumn	This column stores data from a list of choices.
currency	currencyColumn	This column stores currency values.
dateTime	dateTimeColumn	This column stores DateTime values.
geolocation	geolocationColumn	This column stores a geolocation.
lookup	lookupColumn	This column's data is looked up from another source in the site.
number	numberColumn	This column stores number values.
personOrGroup	personOrGroupColumn	This column stores Person or Group values.
text	textColumn	This column stores text values.
validation	columnValidation	This column stores validation formula and message for the column.
hyperlinkOrPicture	hyperlinkOrPictureColumn	This column stores hyperlink or picture values.
term	termColumn	This column stores taxonomy terms.
thumbnail	thumbnailColumn	This column stores thumbnail values.
contentApprovalStatus	contentApprovalStatusColumn	This column stores content approval status.

For a complete version of this table please see the official column definition table.

Create List Column

Refer to the above table to get the Type properties and Column type input. The Type properties are documented within the links in the Type column.

Get list items

In order to use the filter input please refer to the OData filters section.

The column used to filter the output must be indexed, see the Microsoft documentation to add an index to a list.

Limitations

When using $filter and $orderby in the same query to get messages, make sure to specify properties in the following ways:

Properties that appear in $orderby must also appear in $filter.

Properties that appear in $orderby are in the same order as in $filter.

Properties that are present in $orderby appear in $filter before any properties that aren't.

Failing to do this results in the following error:

Error code: InefficientFilter

Error message: The restriction or sort order is too complex for this operation.

The Assign/Remove User License requires either the disabled plans and accompanying SKU IDs to assign licenses or the SKU ID of the license you want to remove.

The Get Security Alert has additional information it can return. There are a large number of fields that don't relate to many alerts, so they are not mapped; you can add them if desired.

Notes

An Introduction to Microsoft Graph API

Microsoft Graph Security API Homepage

Microsoft Graph REST API v1.0 reference

Query Parameters Documentation - OData V4

Microsoft Graph Security API v1.0 refrence

Azure AD OAuth2 flow

Configurations

Microsoft Graph API Asset - Tenant ID

Authenticates using Client Credentials and Tenant ID

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
tenant_id	The Tenant ID.	string	Required
client_ID	The client ID	string	Required
client_Secret	The client secret.	string	Required
scope	List of permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Password Grant (Delegated Authentication)

Authenticates on behalf of a user using oauth 2.0 credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
login_url		string	Optional
tenant_id		string	Required
oauth_un	The username for authentication	string	Required
oauth_pwd	The password for authentication	string	Required
oauth_cl_id	The client ID	string	Required
oauth_cl_secret	The client secret.	string	Required
scope	Permission scopes for this action.	array	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
token_url	Must start with https://login.microsoftonline.com/ and then continue with the tenant_id, and then be prepended with /oauth2/v2.0/token	string	Required
client_id	The client ID	string	Required
client_secret	The client secret.	string	Required
scope	List of permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

MS Graph OpenID Connect Refresh Token Grant

Authenticates using refresh token.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
cl_id	The client ID.	string	Required
cl_secret	The client secret.	string	Required
refresh_token	Refresh Token.	string	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Get Threat Assessment

Retrieve detailed insights on a specific threat by supplying an 'id' to the Microsoft Graph Security API.

Endpoint

URL: /v1.0/informationProtection/threatAssessmentRequests/{{id}}?$expand=results

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Assessment ID

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.type	string	Response data
id	string	Unique identifier
createdDateTime	string	Time value
contentType	string	Type of the resource
expectedAssessment	string	Output field: expectedAssessment
category	string	Output field: category
status	string	Status value
requestSource	string	Output field: requestSource
recipientEmail	string	Output field: recipientEmail
destinationRoutingReason	string	Response reason phrase
contentData	string	Response data
createdBy	object	Output field: createdBy
createdBy.user	object	Output field: createdBy.user
createdBy.user.id	string	Unique identifier
createdBy.user.displayName	string	Name of the resource
[email protected]	string	Response data
results	array	Result of the operation
results.id	string	Unique identifier
results.createdDateTime	string	Result of the operation
results.resultType	string	Type of the resource
results.message	string	Result of the operation

Output Example

{"@odata.context":"string","@odata.type":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","contentType":"string","expectedAssessment":"string","category":"string","status":"active","requestSource":"string","recipientEmail":"string","destinationRoutingReason":"string","contentData":"string","createdBy":{"user":{"id":"12345678-1234-1234-1234-123456789abc","displayName":"Example Name"}},"[email protected]":"string","results":[{"id":"12345678-1234-1234-1234-1234567...

Get Threat Assessment List

Retrieve and analyze threat assessments to enhance security posture using the Microsoft Graph Security API.

Endpoint

URL: /v1.0/informationProtection/threatAssessmentRequests

Method: GET

Input

Argument Name	Type	Required	Description
parameters.filter	string	Optional	Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter
parameters.orderBy	string	Optional	Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph.
parameters.top	number	Optional	Sets the page size of results.

Input Example

{"parameters":{"filter":"string","orderBy":"string","top":123}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
value	array	Value for the parameter
[email protected]	string	Response data
value.id	string	Unique identifier
value.createdDateTime	string	Value for the parameter
value.contentType	string	Type of the resource
value.expectedAssessment	string	Value for the parameter
value.category	string	Value for the parameter
value.status	string	Status value
value.requestSource	string	Value for the parameter
value.recipientEmail	string	Value for the parameter
value.destinationRoutingReason	string	Value for the parameter
value.contentData	string	Response data
value.createdBy	object	Value for the parameter
value.createdBy.user	object	Value for the parameter

Output Example

{"@odata.context":"string","value":[{"@odata.type":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","contentType":"string","expectedAssessment":"string","category":"string","status":"active","requestSource":"string","recipientEmail":"string","destinationRoutingReason":"string","contentData":"string","createdBy":{}}]}

Delete Threat Intelligence Indicator

Removes a specified Threat Intelligence indicator from Microsoft Graph Security API using the unique ID provided.

Endpoint

URL: /beta/security/tiIndicators/{{id}}

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Threat Intelligence Indicator ID

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
error	object	Error message if any
error.code	string	Error message if any
error.message	string	Response message
error.innerError	object	Error message if any
error.innerError.date	string	Error message if any
error.innerError.request-id	string	Unique identifier
error.innerError.client-request-id	string	Unique identifier

Output Example

{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}

Get Threat Intelligence Indicator

Retrieves a specific Threat Intelligence Indicator from Microsoft Graph Security API by using the provided unique ID.

Endpoint

URL: /beta/security/tiIndicators/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Threat Intelligence Indicator ID

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
id	string	Unique identifier
azureTenantId	string	Unique identifier
action	string	Output field: action
additionalInformation	object	Output field: additionalInformation
activityGroupNames	array	Name of the resource
activityGroupNames.file_name	string	Name of the resource
activityGroupNames.file	string	Name of the resource
confidence	object	Unique identifier
description	string	Output field: description
diamondModel	object	Output field: diamondModel
emailEncoding	object	Output field: emailEncoding
emailLanguage	object	Output field: emailLanguage
emailRecipient	object	Output field: emailRecipient
emailSenderAddress	object	Output field: emailSenderAddress
emailSenderName	object	Name of the resource
emailSourceDomain	object	Output field: emailSourceDomain
emailSourceIpAddress	object	Output field: emailSourceIpAddress
emailSubject	object	Output field: emailSubject
emailXMailer	object	Output field: emailXMailer
expirationDateTime	string	Time value
externalId	object	Unique identifier
fileCompileDateTime	object	Time value

Output Example

{"@odata.context":"string","id":"12345678-1234-1234-1234-123456789abc","azureTenantId":"string","action":"string","additionalInformation":{},"activityGroupNames":[{"file_name":"Example Name","file":"string"}],"confidence":{},"description":"string","diamondModel":{},"emailEncoding":{},"emailLanguage":{},"emailRecipient":{},"emailSenderAddress":{},"emailSenderName":{},"emailSourceDomain":{}}

Get Threat Intelligence Indicators List

Retrieve Threat Intelligence indicators from the Microsoft Graph Security API for enhanced analysis and threat detection.

Endpoint

URL: /beta/security/tiIndicators

Method: GET

Input

Argument Name	Type	Required	Description
parameters.filter	string	Optional	Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter
parameters.orderBy	string	Optional	Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph.
parameters.top	number	Optional	Sets the page size of results.

Input Example

{"parameters":{"filter":"string","orderBy":"string","top":123}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
value	array	Value for the parameter
value.id	string	Unique identifier
value.azureTenantId	string	Unique identifier
value.action	string	Value for the parameter
value.additionalInformation	object	Value for the parameter
value.activityGroupNames	array	Name of the resource
value.activityGroupNames.file_name	string	Name of the resource
value.activityGroupNames.file	string	Name of the resource
value.confidence	object	Unique identifier
value.description	string	Value for the parameter
value.diamondModel	object	Value for the parameter
value.emailEncoding	object	Value for the parameter
value.emailLanguage	object	Value for the parameter
value.emailRecipient	object	Value for the parameter
value.emailSenderAddress	object	Value for the parameter
value.emailSenderName	object	Name of the resource
value.emailSourceDomain	object	Value for the parameter
value.emailSourceIpAddress	object	Value for the parameter
value.emailSubject	object	Value for the parameter
value.emailXMailer	object	Value for the parameter
value.expirationDateTime	string	Value for the parameter
value.externalId	object	Unique identifier

Output Example

{"@odata.context":"string","value":[{"id":"12345678-1234-1234-1234-123456789abc","azureTenantId":"string","action":"string","additionalInformation":{},"activityGroupNames":[],"confidence":{},"description":"string","diamondModel":{},"emailEncoding":{},"emailLanguage":{},"emailRecipient":{},"emailSenderAddress":{},"emailSenderName":{},"emailSourceDomain":{},"emailSourceIpAddress":{}}]}

Create Threat Intel Indicator Azure Sentinel

Creates a Threat Intelligence Indicator in Azure Sentinel, including threat type, target product, and TLP level.

Endpoint

URL: /beta/security/tiIndicators

Method: POST

Input

Argument Name	Type	Required	Description
action	string	Optional	The action to apply if the indicator is matched from within the targetProduct security tool. Possible values are unknown, allow, block or alert
activityGroupNames	array	Optional	The cyber threat intelligence name(s) for the parties responsible for the malicious activity covered by the threat indicator
additionalInformation	string	Optional	A catchall area into which extra data from the indicator not covered by the other tiIndicator properties may be placed. Data placed into additionalInformation will typically not be utilized by the targetProduct security tool
azureTenantId	string	Optional	Stamped by the system when the indicator is ingested. The Azure Active Directory tenant id of submitting client
confidence	number	Optional	An integer representing the confidence the data within the indicator accurately identifies malicious behavior. Acceptable values are 0-100 with 100 being the highest.
description	string	Optional	Brief description (100 characters or less) of the threat represented by the indicator
diamondModel	string	Optional	The area of the Diamond Model in which this indicator exists. Possible values are unknown, adversary, capability, infrastructure and victim
domainName	string	Optional	Domain name associated with this indicator. Should be of the format subdomain.domain.topleveldomain (For example, baddomain.domain.net)
emailEncoding	string	Optional	The type of text encoding used in the email
emailLanguage	string	Optional	The Language of the email
emailRecipient	string	Optional	Email Recipient Address
emailSenderAddress	string	Optional	Email Sender Address
emailSenderName	string	Optional	Email Sender Name
emailSourceDomain	string	Optional	Parameter for Create Threat Intel Indicator Azure Sentinel
emailSourceIpAddress	string	Optional	Parameter for Create Threat Intel Indicator Azure Sentinel
emailSubject	string	Optional	Parameter for Create Threat Intel Indicator Azure Sentinel
emailXMailer	string	Optional	X-Mailer value used in the email
expirationDateTime	string	Optional	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time
externalId	string	Optional	Unique identifier
fileCompileDateTime	string	Optional	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time
fileCreatedDateTime	string	Optional	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time
fileHashType	string	Optional	The type of hash stored in fileHashValue. Possible values are unknown, sha1, sha256, md5, authenticodeHash256, lsHash, ctph
fileHashValue	string	Optional	Value for the parameter
fileMutexName	string	Optional	Name of the resource
fileName	string	Optional	Name of the resource

Input Example

{"action":"string","activityGroupNames":["string"],"additionalInformation":"string","azureTenantId":"string","confidence":123,"description":"string","diamondModel":"string","domainName":"Example Name","emailEncoding":"string","emailLanguage":"string","emailRecipient":"string","emailSenderAddress":"string","emailSenderName":"Example Name","emailSourceDomain":"string","emailSourceIpAddress":"string","emailSubject":"string","emailXMailer":"string","expirationDateTime":"string","externalId":"string","fileCompileDateTime":"string","fileCreatedDateTime":"string","fileHashType":"string","fileHashValue":"string","fileMutexName":"Example Name","fileName":"Example Name","filePacker":"string","filePath":"string","fileSize":123,"fileType":"string","isActive":"string","killChain":["string"],"knownFalsePositives":"string","lastReportedDateTime":"string","malwareFamilyNames":"Example Name","networkCidrBlock":"string","networkDestinationAsn":123,"networkDestinationCidrBlock":"string","networkDestinationIPv4":"string","networkDestinationIPv6":"string","networkDestinationPort":123,"networkIPv4":"string","networkIPv6":"string","networkPort":123,"networkProtocol":123,"networkSourceAsn":123,"networkSourceCidrBlock":"string","networkSourceIPv4":"string","networkSourceIPv6":"string","networkSourcePort":123,"passiveOnly":"string"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
id	string	Unique identifier
azureTenantId	string	Unique identifier
action	string	Output field: action
additionalInformation	object	Output field: additionalInformation
activityGroupNames	array	Name of the resource
activityGroupNames.file_name	string	Name of the resource
activityGroupNames.file	string	Name of the resource
confidence	object	Unique identifier
description	string	Output field: description
diamondModel	object	Output field: diamondModel
emailEncoding	object	Output field: emailEncoding
emailLanguage	object	Output field: emailLanguage
emailRecipient	object	Output field: emailRecipient
emailSenderAddress	object	Output field: emailSenderAddress
emailSenderName	object	Name of the resource
emailSourceDomain	object	Output field: emailSourceDomain
emailSourceIpAddress	object	Output field: emailSourceIpAddress
emailSubject	object	Output field: emailSubject
emailXMailer	object	Output field: emailXMailer
expirationDateTime	string	Time value
externalId	object	Unique identifier
fileCompileDateTime	object	Time value

Output Example

Create Threat Intel Indicator Microsoft Defender

Creates a Threat Intelligence Indicator in Microsoft Defender, specifying its action and active status.

Endpoint

URL: /beta/security/tiIndicators

Method: POST

Input

Argument Name	Type	Required	Description
action	string	Optional	The action to apply if the indicator is matched from within the targetProduct security tool. Possible values are unknown, allow, block or alert
activityGroupNames	array	Optional	The cyber threat intelligence name(s) for the parties responsible for the malicious activity covered by the threat indicator
additionalInformation	string	Optional	A catchall area into which extra data from the indicator not covered by the other tiIndicator properties may be placed. Data placed into additionalInformation will typically not be utilized by the targetProduct security tool
azureTenantId	string	Optional	Stamped by the system when the indicator is ingested. The Azure Active Directory tenant id of submitting client
confidence	number	Optional	An integer representing the confidence the data within the indicator accurately identifies malicious behavior. Acceptable values are 0-100 with 100 being the highest.
description	string	Optional	Brief description (100 characters or less) of the threat represented by the indicator
diamondModel	string	Optional	The area of the Diamond Model in which this indicator exists. Possible values are unknown, adversary, capability, infrastructure and victim
domainName	string	Optional	Domain name associated with this indicator. Should be of the format subdomain.domain.topleveldomain (For example, baddomain.domain.net)
emailEncoding	string	Optional	The type of text encoding used in the email
emailLanguage	string	Optional	The Language of the email
emailRecipient	string	Optional	Email Recipient Address
emailSenderAddress	string	Optional	Email Sender Address
emailSenderName	string	Optional	Email Sender Name
emailSourceDomain	string	Optional	Parameter for Create Threat Intel Indicator Microsoft Defender
emailSourceIpAddress	string	Optional	Parameter for Create Threat Intel Indicator Microsoft Defender
emailSubject	string	Optional	Parameter for Create Threat Intel Indicator Microsoft Defender
emailXMailer	string	Optional	X-Mailer value used in the email
expirationDateTime	string	Optional	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time
externalId	string	Optional	Unique identifier
fileCompileDateTime	string	Optional	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time
fileCreatedDateTime	string	Optional	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time
fileHashType	string	Optional	The type of hash stored in fileHashValue. Possible values are unknown, sha1, sha256, md5, authenticodeHash256, lsHash, ctph
fileHashValue	string	Optional	Value for the parameter
fileMutexName	string	Optional	Name of the resource
fileName	string	Optional	Name of the resource

Input Example

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
id	string	Unique identifier
azureTenantId	string	Unique identifier
action	string	Output field: action
additionalInformation	object	Output field: additionalInformation
activityGroupNames	array	Name of the resource
activityGroupNames.file_name	string	Name of the resource
activityGroupNames.file	string	Name of the resource
confidence	object	Unique identifier
description	string	Output field: description
diamondModel	object	Output field: diamondModel
emailEncoding	object	Output field: emailEncoding
emailLanguage	object	Output field: emailLanguage
emailRecipient	object	Output field: emailRecipient
emailSenderAddress	object	Output field: emailSenderAddress
emailSenderName	object	Name of the resource
emailSourceDomain	object	Output field: emailSourceDomain
emailSourceIpAddress	object	Output field: emailSourceIpAddress
emailSubject	object	Output field: emailSubject
emailXMailer	object	Output field: emailXMailer
expirationDateTime	string	Time value
externalId	object	Unique identifier
fileCompileDateTime	object	Time value

Output Example

Post Threat Assessment Email

Submits an email to Microsoft Graph API for threat assessment, analyzing recipient and attachments for security risks.

Endpoint

URL: /v1.0/informationProtection/threatAssessmentRequests

Method: POST

Input

Argument Name	Type	Required	Description
attachments	array	Optional	Parameter for Post Threat Assessment Email
attachments.contentData	string	Optional	Response data
recipientEmail	string	Optional	The mail recipient whose policies are used to assess the mail
expectedAssessment	string	Optional	The expected assessment from the ubmitter. Possible values are block, unblock
category	string	Optional	The threat category. Possible values are spam, phishing, malware

Input Example

{"attachments":[{"contentData":"string"}],"recipientEmail":"string","expectedAssessment":"string","category":"string"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
error	object	Error message if any
error.code	string	Error message if any
error.message	string	Response message
error.innerError	object	Error message if any
error.innerError.date	string	Error message if any
error.innerError.request-id	string	Unique identifier
error.innerError.client-request-id	string	Unique identifier

Output Example

{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}

Post Threat Assessment File

Submits a file to Microsoft Graph API for a comprehensive security threat assessment, requiring an attachment.

Endpoint

URL: /v1.0/informationProtection/threatAssessmentRequests

Method: POST

Input

Argument Name	Type	Required	Description
attachments	array	Optional	Parameter for Post Threat Assessment File
attachments.contentData	string	Optional	Response data
attachments.fileName	string	Optional	Name of the resource
expectedAssessment	string	Optional	The expected assessment from the ubmitter. Possible values are block, unblock
category	string	Optional	The threat category. Possible values are spam, phishing, malware

Input Example

{"attachments":[{"contentData":"string","fileName":"Example Name"}],"expectedAssessment":"string","category":"string"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
error	object	Error message if any
error.code	string	Error message if any
error.message	string	Response message
error.innerError	object	Error message if any
error.innerError.date	string	Error message if any
error.innerError.request-id	string	Unique identifier
error.innerError.client-request-id	string	Unique identifier

Output Example

{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}

Post Threat Assessment URI

Submits a URI to Microsoft Graph API for threat assessment, requiring 'messageUri' and 'recipientEmail' in the JSON body.

Endpoint

URL: /v1.0/informationProtection/threatAssessmentRequests

Method: POST

Input

Argument Name	Type	Required	Description
messageUri	string	Optional	The resource URI of the mail message for assessment
recipientEmail	string	Optional	The mail recipient whose policies are used to assess the mail
expectedAssessment	string	Optional	The expected assessment from the ubmitter. Possible values are block, unblock
category	string	Optional	The threat category. Possible values are spam, phishing, malware

Input Example

{"messageUri":"string","recipientEmail":"string","expectedAssessment":"string","category":"string"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
error	object	Error message if any
error.code	string	Error message if any
error.message	string	Response message
error.innerError	object	Error message if any
error.innerError.date	string	Error message if any
error.innerError.request-id	string	Unique identifier
error.innerError.client-request-id	string	Unique identifier

Output Example

{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}

Post Threat Assessment URL

Initiates a security threat assessment for a specified URL via Microsoft Graph API to identify potential risks. Requires a 'url' in the JSON body.

Endpoint

URL: /v1.0/informationProtection/threatAssessmentRequests

Method: POST

Input

Argument Name	Type	Required	Description
url	string	Optional	The URL string
expectedAssessment	string	Optional	The expected assessment from the ubmitter. Possible values are block, unblock
category	string	Optional	The threat category. Possible values are spam, phishing, malware

Input Example

{"url":"https://example.com/api/resource","expectedAssessment":"string","category":"string"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
error	object	Error message if any
error.code	string	Error message if any
error.message	string	Response message
error.innerError	object	Error message if any
error.innerError.date	string	Error message if any
error.innerError.request-id	string	Unique identifier
error.innerError.client-request-id	string	Unique identifier

Output Example

{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}

Response Headers

Header	Description	Example
Cache-Control	Directives for caching mechanisms
client-request-id	HTTP response header: client-request-id
Content-Encoding	HTTP response header: Content-Encoding
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT
Location	The URL to redirect a page to
OData-Version	HTTP response header: OData-Version
request-id	HTTP response header: request-id
Strict-Transport-Security	HTTP response header: Strict-Transport-Security
Transfer-Encoding	HTTP response header: Transfer-Encoding
Vary	HTTP response header: Vary
x-ms-ags-diagnostic	HTTP response header: x-ms-ags-diagnostic