Microsoft Graph Security
Triage security alerts and incidents, monitor Secure Score, and run advanced hunting queries against Microsoft 365 Defender through the Microsoft Graph security API.
What you can ask
- List high-severity alerts from the last 24 hours and group them by incident
- Run an advanced hunting query for sign-ins from a suspicious IP address
- Report the current Secure Score and the controls with the largest score impact
Set up
Microsoft Graph Security needs an OAuth application from your organization before anyone can connect. An organization admin completes these steps once.
- Go to Organization > Connectors and find Microsoft Graph Security. Click Enable, and choose which tools to allow.
- Create an OAuth application in the Microsoft Graph Security developer portal.
- Add the Redirect URI shown in the connector settings to the application.
- Copy the application's Client ID and Client Secret into the connector, then save it.
- Each member connects their own account the first time they use it.
⚠️ Warning: Do not enter your Devs.ai or Microsoft Graph Security login email or password in the OAuth application fields.
To use one account for the whole organization, turn on Share one connection with everyone. Every member's agents then act as that account, with exactly the access it has.
OAuth scopes used by these tools (8)
Grant the scopes for the tools you plan to allow.
SecurityAlert.Read.AllSecurityAlert.ReadWrite.AllSecurityEvents.Read.AllSecurityEvents.ReadWrite.AllSecurityIncident.Read.AllSecurityIncident.ReadWrite.AllThreatHunting.Read.AllUser.Read
Tools
Microsoft Graph Security offers 13 tools. Admins choose which ones agents can use. See Tool permission groups.
Read (10)
View and search information without changing it.
| Tool | What it does |
|---|---|
get_alert | Get a single security alert by ID, including its full evidence. |
get_incident | Get a single security incident by ID. |
get_secure_score | Get a single Secure Score snapshot by ID, including its per-control score breakdown. |
get_secure_score_control_profile | Get a single Secure Score control profile by ID. |
list_alerts | List security alerts (alerts_v2), correlated into incidents. |
list_incidents | List security incidents - groups of correlated alerts from the same attack. |
list_secure_score_control_profiles | List Secure Score control profiles - the security controls behind the tenant's Secure Score, with current state (Default/Ignored/ThirdParty/Reviewed). |
list_secure_scores | List Microsoft Secure Score snapshots for the tenant over time. |
run_hunting_query | Run a KQL advanced hunting query against the Microsoft 365 Defender schema (device, email, identity, cloud app tables). |
validate_credential | Validate Microsoft Graph Security credentials by calling GET /me on Microsoft Graph. |
Delete or overwrite (3)
Remove or replace existing data.
| Tool | What it does |
|---|---|
update_alert | Update a security alert's status, classification, determination, assignment, or custom details. |
update_incident | Update a security incident's status, classification, determination, severity, name, description, summary, custom tags, assignment, or resolving comment. |
update_secure_score_control_profile | Update a Secure Score control profile, typically to mark it Ignored/ThirdParty/Reviewed via control_state_updates. vendor_provider and vendor_name are required by the Graph API - call get_secure_score_control_profile first and pass back its current vendorInformation provider/vendor values (commonly 'SecureScore'/'Microsoft'). |