Azure Sentinel API Documentation

This documentation provides a comprehensive guide to interacting with the Azure Sentinel API, allowing you to programmatically manage security incidents, alerts, entities, and more.

Introduction

Azure Sentinel is a cloud-native Security Information and Event Management (SIEM) and Security Orchestration, Automation, and Response (SOAR) solution. The API enables seamless integration with your existing security workflows and tools.

All API endpoints are accessed via HTTPS. The base URL for the API is:

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/

Ensure you replace {subscriptionId} and {resourceGroupName} with your actual Azure subscription ID and resource group name respectively.

Authentication

All Azure Sentinel API requests must be authenticated. Azure Sentinel uses Azure Active Directory (Azure AD) for authentication. You will need to obtain an OAuth 2.0 access token.

Using Service Principals

A common method is to use a Service Principal. Ensure the Service Principal has the necessary permissions (e.g., "Azure Sentinel Responder" role) for the actions you intend to perform.

Request an access token from Azure AD endpoints like:

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}&scope=https://management.azure.com/.default

The obtained access token should be included in the Authorization header of your API requests:

Authorization: Bearer {accessToken}

Entities API

The Entities API allows you to manage and query security-related entities within Azure Sentinel, such as IP addresses, users, and hostnames.

List Entities

GET /entities?kind={entityType}

Retrieves a list of entities of a specified type.

Query Parameters:

Name Type Description
kind String The type of entity to retrieve (e.g., ipAddress, account, host).
filter String (OData) OData filter clause for advanced filtering.
limit Integer Maximum number of entities to return.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/entities?kind=ipAddress' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "value": [
        {
            "kind": "ipAddress",
            "properties": {
                "address": "192.168.1.1",
                "isRemote": false,
                "threatIntelligenceTags": ["Malicious IP"],
                "lastSeenTimeUtc": "2023-10-27T10:00:00Z"
            }
        },
        {
            "kind": "ipAddress",
            "properties": {
                "address": "10.0.0.5",
                "isRemote": true,
                "threatIntelligenceTags": [],
                "lastSeenTimeUtc": "2023-10-26T15:30:00Z"
            }
        }
    ]
}

Get Entity

GET /entities/{entityId}

Retrieves a specific entity by its ID.

Path Parameters:

Name Type Description
entityId String (GUID) The unique identifier of the entity.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/entities/a1b2c3d4-e5f6-7890-1234-abcdef123456' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "kind": "account",
    "properties": {
        "principalName": "user@example.com",
        "netBiosName": "USERPC",
        "host": {
            "hostName": "DESKTOP-XYZ",
            "domainName": "EXAMPLE.COM"
        },
        "aadTenantId": "your-aad-tenant-id",
        "aadUserId": "user-guid",
        "lastSeenTimeUtc": "2023-10-27T11:00:00Z"
    }
}

Incidents API

Manage security incidents detected by Azure Sentinel.

List Incidents

GET /incidents

Retrieves a list of security incidents.

Query Parameters:

Name Type Description
filter String (OData) OData filter clause for advanced filtering (e.g., by status, severity).
orderBy String (OData) OData order by clause.
limit Integer Maximum number of incidents to return.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/incidents?filter=status eq "New"' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "value": [
        {
            "id": "incident-guid-1",
            "name": "Suspicious Login Activity",
            "properties": {
                "title": "Suspicious Login Activity Detected",
                "description": "Multiple failed login attempts from an unusual IP address.",
                "severity": "Medium",
                "status": "New",
                "createdTimeUtc": "2023-10-27T09:00:00Z",
                "lastModifiedTimeUtc": "2023-10-27T09:00:00Z",
                "owner": null
            }
        },
        {
            "id": "incident-guid-2",
            "name": "Malware Detected on Server",
            "properties": {
                "title": "Malware Detected on Server XYZ",
                "description": "Antivirus detected a known malware signature on server XYZ.",
                "severity": "High",
                "status": "InProgress",
                "createdTimeUtc": "2023-10-26T14:00:00Z",
                "lastModifiedTimeUtc": "2023-10-27T08:00:00Z",
                "owner": { "objectId": "owner-guid", "email": "analyst@example.com", "assignedBy": "Manual" }
            }
        }
    ]
}

Create Incident

POST /incidents/{incidentId}

Creates a new incident.

Path Parameters:

Name Type Description
incidentId String (GUID) The ID for the new incident. If not provided, a new GUID will be generated.

Request Body:


{
    "properties": {
        "title": "Phishing Attempt Detected",
        "description": "User reported a suspicious email.",
        "severity": "Low",
        "status": "New",
        "incidentLabels": [
            { "labelName": "Phishing", "labelType": "User" }
        ],
        "relatedAnalyticRuleIds": ["rule-id-1", "rule-id-2"]
    }
}

Example Request:


curl -X POST \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/incidents/NEW_INCIDENT_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "properties": {
            "title": "Phishing Attempt Detected",
            "description": "User reported a suspicious email.",
            "severity": "Low",
            "status": "New",
            "incidentLabels": [ { "labelName": "Phishing", "labelType": "User" } ],
            "relatedAnalyticRuleIds": ["rule-id-1", "rule-id-2"]
        }
    }'

Example Response (201 Created):


{
    "id": "incident-guid-3",
    "name": "Phishing Attempt Detected",
    "properties": {
        "title": "Phishing Attempt Detected",
        "description": "User reported a suspicious email.",
        "severity": "Low",
        "status": "New",
        "createdTimeUtc": "2023-10-27T12:00:00Z",
        "lastModifiedTimeUtc": "2023-10-27T12:00:00Z",
        "incidentLabels": [ { "labelName": "Phishing", "labelType": "User" } ],
        "relatedAnalyticRuleIds": ["rule-id-1", "rule-id-2"]
    }
}

Get Incident

GET /incidents/{incidentId}

Retrieves a specific incident by its ID.

Path Parameters:

Name Type Description
incidentId String (GUID) The unique identifier of the incident.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/incidents/incident-guid-1' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "id": "incident-guid-1",
    "name": "Suspicious Login Activity",
    "properties": {
        "title": "Suspicious Login Activity Detected",
        "description": "Multiple failed login attempts from an unusual IP address.",
        "severity": "Medium",
        "status": "New",
        "createdTimeUtc": "2023-10-27T09:00:00Z",
        "lastModifiedTimeUtc": "2023-10-27T09:00:00Z",
        "owner": null,
        "entities": [
            {
                "entityId": "entity-guid-ip",
                "kind": "ipAddress",
                "properties": { "address": "192.168.1.1" }
            },
            {
                "entityId": "entity-guid-user",
                "kind": "account",
                "properties": { "principalName": "user@example.com" }
            }
        ],
        "alerts": [
            { "alertId": "alert-guid-1", "alertName": "High Number of Failed Logins" }
        ]
    }
}

Update Incident

PUT /incidents/{incidentId}

Updates an existing incident. You can update fields like status, severity, title, description, and assign an owner.

Path Parameters:

Name Type Description
incidentId String (GUID) The unique identifier of the incident to update.

Request Body:

Provide only the fields you wish to update.


{
    "properties": {
        "status": "InProgress",
        "severity": "High",
        "owner": {
            "objectId": "analyst-guid-123",
            "email": "analyst@example.com",
            "assignedBy": "Manual"
        }
    }
}

Example Request:


curl -X PUT \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/incidents/incident-guid-1' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "properties": {
            "status": "InProgress",
            "severity": "High",
            "owner": {
                "objectId": "analyst-guid-123",
                "email": "analyst@example.com",
                "assignedBy": "Manual"
            }
        }
    }'

Example Response (200 OK):


{
    "id": "incident-guid-1",
    "name": "Suspicious Login Activity",
    "properties": {
        "title": "Suspicious Login Activity Detected",
        "description": "Multiple failed login attempts from an unusual IP address.",
        "severity": "High",
        "status": "InProgress",
        "createdTimeUtc": "2023-10-27T09:00:00Z",
        "lastModifiedTimeUtc": "2023-10-27T13:00:00Z",
        "owner": { "objectId": "analyst-guid-123", "email": "analyst@example.com", "assignedBy": "Manual" }
    }
}

Alerts API

Interact with security alerts generated by Azure Sentinel analytics rules.

List Alerts

GET /alerts

Retrieves a list of alerts.

Query Parameters:

Name Type Description
filter String (OData) OData filter clause for advanced filtering.
limit Integer Maximum number of alerts to return.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/alerts?filter=alertSeverity eq "High"' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "value": [
        {
            "id": "alert-guid-1",
            "name": "High Number of Failed Logins",
            "properties": {
                "alertDisplayName": "High Number of Failed Logins",
                "description": "Detected an unusually high number of failed login attempts.",
                "severity": "High",
                "alertType": "AnomalousLoginActivity",
                "timeGenerated": "2023-10-27T09:00:00Z",
                "entities": [...]
            }
        }
    ]
}

Get Alert

GET /alerts/{alertId}

Retrieves a specific alert by its ID.

Path Parameters:

Name Type Description
alertId String (GUID) The unique identifier of the alert.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/alerts/alert-guid-1' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "id": "alert-guid-1",
    "name": "High Number of Failed Logins",
    "properties": {
        "alertDisplayName": "High Number of Failed Logins",
        "description": "Detected an unusually high number of failed login attempts.",
        "severity": "High",
        "alertType": "AnomalousLoginActivity",
        "timeGenerated": "2023-10-27T09:00:00Z",
        "entities": [
            {
                "entityId": "entity-guid-ip",
                "kind": "ipAddress",
                "properties": { "address": "192.168.1.1" }
            },
            {
                "entityId": "entity-guid-user",
                "kind": "account",
                "properties": { "principalName": "user@example.com" }
            }
        ],
        "vendorProductName": "Microsoft Azure",
        "productComponentName": "Azure Sentinel"
    }
}

Bookmarks API

Create and manage bookmarks to save specific query results for later investigation.

List Bookmarks

GET /bookmarks

Retrieves a list of bookmarks.

Query Parameters:

Name Type Description
filter String (OData) OData filter clause for advanced filtering.
orderBy String (OData) OData order by clause.
limit Integer Maximum number of bookmarks to return.

Example Request:


curl -X GET \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/bookmarks' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example Response (200 OK):


{
    "value": [
        {
            "id": "bookmark-guid-1",
            "name": "Suspicious IP Activity - 192.168.1.1",
            "properties": {
                "displayName": "Suspicious IP Activity",
                "query": "SecurityEvent | where IPAddress == '192.168.1.1'",
                "queryResult": "[ { \"IPAddress\": \"192.168.1.1\", \"Timestamp\": \"2023-10-27T10:00:00Z\" } ]",
                "createdTimeUtc": "2023-10-27T10:15:00Z",
                "labels": [ { "labelName": "Investigation", "labelType": "User" } ],
                "incident": null
            }
        }
    ]
}

Create Bookmark

POST /bookmarks/{bookmarkId}

Creates a new bookmark.

Path Parameters:

Name Type Description
bookmarkId String (GUID) The ID for the new bookmark. If not provided, a new GUID will be generated.

Request Body:


{
    "properties": {
        "displayName": "Potential Malicious Host",
        "query": "Heartbeat | where Computer == 'MALICIOUS-PC'",
        "queryResult": "[ { \"Computer\": \"MALICIOUS-PC\", \"TimeGenerated\": \"2023-10-27T11:30:00Z\" } ]",
        "notes": "This host shows unusual network activity. Further investigation needed.",
        "labels": [
            { "labelName": "Suspicious Activity", "labelType": "User" }
        ]
    }
}

Example Request:


curl -X POST \
  'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SecurityInsights/bookmarks/NEW_BOOKMARK_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "properties": {
            "displayName": "Potential Malicious Host",
            "query": "Heartbeat | where Computer == \"MALICIOUS-PC\"",
            "queryResult": "[ { \"Computer\": \"MALICIOUS-PC\", \"TimeGenerated\": \"2023-10-27T11:30:00Z\" } ]",
            "notes": "This host shows unusual network activity. Further investigation needed.",
            "labels": [ { "labelName": "Suspicious Activity", "labelType": "User" } ]
        }
    }'

Example Response (201 Created):


{
    "id": "bookmark-guid-2",
    "name": "Potential Malicious Host",
    "properties": {
        "displayName": "Potential Malicious Host",
        "query": "Heartbeat | where Computer == 'MALICIOUS-PC'",
        "queryResult": "[ { \"Computer\": \"MALICIOUS-PC\", \"TimeGenerated\": \"2023-10-27T11:30:00Z\" } ]",
        "createdTimeUtc": "2023-10-27T11:45:00Z",
        "lastModifiedTimeUtc": "2023-10-27T11:45:00Z",
        "notes": "This host shows unusual network activity. Further investigation needed.",
        "labels": [ { "labelName": "Suspicious Activity", "labelType": "User" } ],
        "incident": null
    }
}