You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Import threat intelligence to Microsoft Sentinel with the STIX objects API (Preview)
12
12
13
-
Import indicators of compromise and other domain objects in the STIX format into a Microsoft Sentinel workspace with the Microsoft Sentinel STIX objects API. Whether you're using a threat intelligence platform or a custom application, use this document as a supplemental reference to the instructions in the [Microsoft Sentinel upload indicators API data connector](connect-threat-intelligence-upload-api.md). Installing the data connector isn't required to connect to the API.
13
+
Import indicators of compromise and other STIX domain objects to use in Microsoft Sentinel workspace with the STIX objects API. Whether you're using a threat intelligence platform or a custom application, use this document as a supplemental reference to the instructions in the [Microsoft Sentinel STIX objects API data connector](connect-threat-intelligence-upload-api.md). Installing the data connector isn't required to connect to the API.
14
14
15
15
> [!IMPORTANT]
16
16
> This API is currently in PREVIEW. The [Azure Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
17
17
>
18
18
19
-
Structured Threat Information Expression (STIX) is a language for expressing cyber threat and observable information. STIX objects API includes the following enhanced support for domain objects:
20
-
-indicators
19
+
Structured Threat Information Expression (STIX) is a language for expressing cyber threat and observable information. Enhanced support for the following domain objects is included with the STIX objects API:
20
+
-indicator
21
21
- attack pattern
22
-
- threat actors
22
+
- threat actor
23
23
- identity
24
-
-relationships
24
+
-relationship
25
25
26
26
For more information, see [Introduction to STIX](https://oasis-open.github.io/cti-documentation/stix/intro.html).
27
27
28
28
> [!NOTE]
29
-
> The previous upload indicators API is now deprecated. If you need to reference that API while transitioning to the new STIX objects API, see [Legacy upload indicators API](upload-indicators-api.md).
29
+
> The previous upload indicators API is now legacy. If you need to reference that API while transitioning to the new STIX objects API, see [Legacy upload indicators API](upload-indicators-api.md).
30
30
31
31
## Call the API
32
32
@@ -40,7 +40,7 @@ A call to the STIX objects API has five components:
40
40
41
41
## Register your client application with Microsoft Entra ID
42
42
43
-
In order to authenticate to Microsoft Sentinel, the request to the STIX objects API requires a valid Microsoft Entra access token. For more information on application registration, see [Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app) or see the basic steps as part of the [upload indicators API data connector](connect-threat-intelligence-upload-api.md#register-an-azure-ad-application) setup.
43
+
In order to authenticate to Microsoft Sentinel, the request to the STIX objects API requires a valid Microsoft Entra access token. For more information on application registration, see [Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app) or see the basic steps as part of the [STIX objects API data connector](connect-threat-intelligence-upload-api.md#register-an-azure-ad-application) setup.
44
44
45
45
This API requires the calling Microsoft Entra application to be granted the Microsoft Sentinel contributor role at the workspace level.
46
46
@@ -92,7 +92,7 @@ The JSON object for the body contains the following fields:
92
92
93
93
Create the array of STIX objects using the STIX format specification. Some of the STIX property specifications are expanded here for your convenience with links to the relevant STIX document sections. Also note some properties, while valid for STIX, don't have corresponding object schema properties in Microsoft Sentinel.
94
94
95
-
#### Indicators
95
+
#### Indicator
96
96
97
97
|Property Name |Type | Description |
98
98
|----|----|----|
@@ -141,7 +141,7 @@ The response header contains an HTTP status code. Reference this table for more
141
141
142
142
|Status code |Description |
143
143
|---------|---------|
144
-
|**200**| Success. The API returns 200 when one or more indicators are successfully validated and published. |
144
+
|**200**| Success. The API returns 200 when one or more STIX objects are successfully validated and published. |
145
145
|**400**| Bad format. Something in the request isn't correctly formatted. |
146
146
|**401**| Unauthorized. |
147
147
|**404**| File not found. Usually this error occurs when the workspace ID isn't found. |
@@ -158,14 +158,14 @@ The response body is an array of error messages in JSON format:
158
158
159
159
|Field name | Data Type | Description |
160
160
|----|----|----|
161
-
|recordIndex | int | Index of the indicators in the request |
161
+
|recordIndex | int | Index of the STIX objects in the request |
162
162
|errorMessages | Array of strings | Error messages |
163
163
164
164
165
165
## Throttling limits for the API
166
166
167
167
All limits are applied per user:
168
-
- 100 indicators per request.
168
+
- 100 objects per request.
169
169
- 100 requests per minute.
170
170
171
171
If there are more requests than the limit, a `429` http status code in the response header is returned with the following response body:
@@ -175,11 +175,11 @@ If there are more requests than the limit, a `429` http status code in the respo
175
175
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
176
176
}
177
177
```
178
-
Approximately 10,000 indicators per minute is the maximum throughput before a throttling error is received.
178
+
Approximately 10,000 objects per minute is the maximum throughput before a throttling error is received.
179
179
180
180
### Sample indicator request body
181
181
182
-
The following example shows how to represent two indicators in the STIX specification. `Test Indicator 2`showcases setting the TLP to white with the mapped object marking, and clarifying its description and labels are in English.
182
+
The following example shows how to represent two indicators in the STIX specification. `Test Indicator 2`highlights the Traffic Light Protocol (TLP) set to white with the mapped object marking, and clarifying its description and labels are in English.
183
183
184
184
```json
185
185
{
@@ -253,9 +253,9 @@ The following example shows how to represent two indicators in the STIX specific
253
253
```
254
254
255
255
### Sample response body with validation error
256
-
If all indicators are validated successfully, an HTTP 200 status is returned with an empty response body.
256
+
If all STIX objects are validated successfully, an HTTP 200 status is returned with an empty response body.
257
257
258
-
If validation fails for one or more indicators, the response body is returned with more information. For example, if you send an array with four indicators, and the first three are good but the fourth doesn't have an `id` (a required field), then an HTTP status code 200 response is generated along with the following body:
258
+
If validation fails for one or more objects, the response body is returned with more information. For example, if you send an array with four indicators, and the first three are good but the fourth doesn't have an `id` (a required field), then an HTTP status code 200 response is generated along with the following body:
259
259
260
260
```json
261
261
{
@@ -269,13 +269,13 @@ If validation fails for one or more indicators, the response body is returned wi
269
269
]
270
270
}
271
271
```
272
-
The indicators are sent as an array, so the `recordIndex` begins at `0`.
272
+
The objects are sent as an array, so the `recordIndex` begins at `0`.
273
273
274
274
### Other samples
275
275
276
276
#### Sample indicator
277
277
278
-
In this example, the indicator is marked with the green TLP. More extension attributes of `toxicity` and `rank` are also included. Although these properties aren't in the Microsoft Sentinel schema for indicators, ingesting an indicator with these properties doesn't trigger an error. The properties just aren't referenced or indexed in the workspace.
278
+
In this example, the indicator is marked with the green TLP. More extension attributes of `toxicity` and `rank` are also included. Although these properties aren't in the Microsoft Sentinel schema for indicators, ingesting an object with these properties doesn't trigger an error. The properties simply aren't referenced or indexed in the workspace.
279
279
280
280
```json
281
281
{
@@ -580,246 +580,6 @@ In this example, the indicator is marked with the green TLP. More extension attr
"description": "menuPass appears to favor spear phishing to deliver payloads to the intended targets. While the attackers behind menuPass have used other RATs in their campaign, it appears that they use PIVY as their primary persistence mechanism.",
0 commit comments