Use the Microsoft Graph APIs for Microsoft Defender Threat Intelligence
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.