Use the Microsoft Graph APIs for Microsoft Defender Threat Intelligence (preview)

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Note

The Microsoft Graph API for Microsoft Defender Threat Intelligence requires an active Defender Threat Intelligence Portal license and API add-on license for the tenant.

Organizations conducting threat infrastructure analysis and gathering threat intelligence can use Microsoft Defender Threat Intelligence (Defender TI) to streamline triage, incident response, threat hunting, vulnerability management, and cyber threat intelligence analyst workflows. In addition, you can use the APIs exposed by Microsoft Defender Threat Intelligence on Microsoft Graph to deliver world-class threat intelligence that helps protect your organization from modern cyber threats. You can identify adversaries and their operations, accelerate detection and remediation, and enhance your security investments and workflows.

These threat intelligence APIs allow you to operationalize intelligence found within the UI. This includes finished intelligence in the forms of articles and intel profiles, machine intelligence including indicators of compromise (IoCs) and reputation verdicts, and finally, enrichment data including passive DNS, cookies, components, and trackers.

Authorization

To call the threat intelligence APIs in Microsoft Graph, your app needs to acquire an access token. For details about access tokens, see Get access tokens to call Microsoft Graph. Your app also needs the appropriate permissions. For more information, see Threat intelligence permissions.

Common use cases

The threat intelligence APIs fall into a few main categories:

• Written details about a threat or threat actor, such as article and intelligenceProfile.
• Properties about a host, such as hostCookie, passiveDns, or whois.

The following table lists some common use cases for the threat intelligence APIs.

Use cases	REST resources	See also
Read articles about threat intelligence.	article	Methods of article
Read information about a host which is currently or was previously available on the internet and that Microsoft Defender Threat Intelligence detected. You can get further details about a host including associated cookies, passive DNS entries, reputation, and more.	host, hostCookie, passiveDnsRecord, hostReputation	Methods of host
Read information about web components observed on a host.	hostComponent	Methods of hostComponent
Read information about cookies observed on a host.	hostCookie	Methods of hostCookie
Discover referential host pairs observed about a host. Host pairs include details such as information about HTTP redirections, consumption of CSS or images from a host, and more.	hostPair	Methods of hostPair
Discover information about ports that Microsoft Defender Threat Intelligence has observed on a host, including components on those ports, the number of times that a port has been observed, and what each host port banner response contains.	hostPort, hostPortComponent, hostPortBanner	Methods of hostPort
Read SSL certificate data observered on a host. This data includes information about the SSL certificate and the relationship between the host and the SSL certificate.	hostSslCertificate, sslCertificate	Methods of hostSslCertificate
Read Internet trackers observed on a host.	hostTracker	Methods of hosttracker
Read intelligence profiles about threat actors and common tools of compromise.	intelligenceProfile, intelligenceProfileIndicator	Methods of intelligenceProfile
Read passive DNS (PDNS) records about a host.	passiveDnsRecord	Methods of passiveDnsRecord
Read SSL certificate data. This information is standalone from the details about how the SSL certificate relates to a host.	sslCertificate	Methods of sslCertificate
Read subdomain details for a host.	subdomain	Methods of subdomain
Read details about a vulnerability.	vulnerability	Methods of vulnerability
Read WHOIS details for a host.	whoisRecord	Methods of whoisRecord

Next steps

The threat intelligence APIs in Microsoft Graph can help protect your organization from modern cyber threats. To learn more:

• Drill down on the methods and properties of the resources most helpful to your scenario.
• Try the API in the Graph Explorer.