Closed ErikDelfgaauw closed 1 year ago
@ErikDelfgaauw Thanks for your feedback! We will investigate and update as appropriate.
Hi @ErikDelfgaauw The Azure Sentinel API is available in all Azure regions. You can use the Traffic Light Protocol (TLP) to indicate the sensitivity of the indicator. The TLP can be added to the sample request body as a custom field. You can find more information about uploading indicators to Azure Sentinel API in the following link https://learn.microsoft.com/en-us/azure/sentinel/upload-indicators-api
Hi @ManoharLakkoju-MSFT Can you give an example of how to add the TLP to the sample request body as a custom field or specify where this is documented? There is nothing about this on https://learn.microsoft.com/en-us/azure/sentinel/upload-indicators-api.
@ErikDelfgaauw, thank you for this great feedback! The TLP information and example is sorely missing from the upload indicator API article. So, I have just added some clarification to the article https://learn.microsoft.com/en-us/azure/sentinel/upload-indicators-api that is now live.
The TLP needs to use one of four possible marking-definition IDs from https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_yd3ar14ekwrs in the object_marking_refs
section. Since JSON doesn't allow comments, it may still be difficult to pick this out from the reference. I am changing the Sample request body to use TLP white with this edit,
"object_marking_refs": [ "marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9" ],
and I added some clarity to the reference section for the object_marking_refs
property.
Let us know if that helps!
@austinmccollum Thanks for your inputs.
@ErikDelfgaauw if there are any further questions regarding the documentation, please tag me in your reply and we will be happy to continue the conversation.
@ManoharLakkoju-MSFT @austinmccollum I only see a change to the condensed indicator format specification regarding TLP in the documentation, but I don't see TLP added to the Sample Request Body yet.
Also, I already tried the following in the very beginning, but it doesn't work (indicator is added, but TrafficLightProtocolLevel remains "unknown" in the ThreatIntelligenceIndicator table:
{
"sourcesystem": "X",
"value": [
{
"id": "indicator--f7a182a1-ae48-41fb-a0ad-5f8babd09fa3",
"spec_version": "2.1",
"created": "2023-06-22T05:07:24Z",
"modified": "2023-06-22T05:07:24Z",
"type": "indicator",
"name": "X",
"description": "This indicator is provided by the X Project",
"indicator_types": [
"malicious-activity"
],
"pattern": "[ ipv4-addr:value = 'X.X.X.X' ]",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-06-22T05:07:24Z",
"valid_until": "2023-07-06T05:07:24Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
],
"created_by_ref": "identity--0f4a0bd8-c80c-4214-97a9-ea2190d0d216",
"revoked": false,
"labels": [
"X"
],
"confidence": 50,
"lang": "en",
"object_marking_refs": [
"marking-definition--48fd9b67-db96-4eda-9656-c6e4f0b3cb97"
],
"external_references": [
{
"source_name": "X",
"description": "X Project",
"external_id": "55c9fb59-d362-4adc-8d00-b33361a2df00",
"url": "https://x.x.com"
}
],
"granular_markings": null
},
{
"id": "marking-definition--48fd9b67-db96-4eda-9656-c6e4f0b3cb97",
"spec_version": "2.1",
"created": "2023-06-22T05:07:24Z",
"type": "marking-definition",
"name": "TLP:GREEN",
"definition_type": "tlp",
"definition": {
"tlp": "green"
}
}
]
}
This returns:
{
"errors": [
{
"recordIndex": 1,
"errorMessages": [
"Error for Property=spec_version: Please ensure that your indicators' spec_versions matches their properties. Actual value: 2.1."
]
}
]
}
And again: the result is that the indicator is added, but without TLP.
I think the 7.2.1.4 section of the STIX reference is confusing. So this is good feedback for me to more plainly show how to designate TLP in the sample request body. How about this:
As section 7.2.1.4 section shows, there are 4 valid TLP designations. When designating indicator objects, use the well-known marking-definition ID for the appropriate color in the object_marking_refs
array.
For example, to designate an indicator as TLP green, the object_marking_refs
section would be written exactly like this:
"object_marking_refs": [
"marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
],
to designate an indicator as TLP clear or white, the object_marking_refs
would be written like it has been edited in the sample
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
To show the whole context, here's the complete sample body request for an indicator with white TLP:
{
"sourcesystem": "test",
"value": [
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52",
"created": "2023-01-01T18:29:07.778Z",
"modified": "2025-02-26T18:29:07.778Z",
"created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7",
"revoked": false,
"labels": [
"label 1",
"label 2"
],
"confidence": 55,
"lang": "en",
"external_references": [
{
"source_name": "External Test Source",
"description": "Test Report",
"external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f",
"url": "https://fabrikam.com//testreport.json",
"hashes": {
"SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
}
}
],
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
"granular_markings": [
{
"marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80",
"selectors": [
"description",
"labels"
],
"lang": "en"
},
{
"marking_ref": "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82",
"selectors": [
"indicator_types.[1]"
]
}
],
"name": "Test Indicator 2",
"description": "This is a test indicator with all valid fields including TLP",
"indicator_types": [
"threatstream-severity-low",
"threatstream-confidence-80"
],
"pattern": "[ipv4-addr:value = '192.168.1.1']",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-01-01T18:29:07.778Z",
"valid_until": "2025-02-26T18:29:07.778Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
]
}
]
}
@austinmccollum Aaah, so those marking_defintion GUIDs are FIXED for the various TLP levels and there's no need to specify them separately in the request with a dynamic generated GUID as a relationship identifier!
Thanks a lot for this clarification, it's working now!
@ErikDelfgaauw We are going to close this thread as resolved but if there are any further questions regarding the documentation, please tag me in your reply and we will be happy to continue the conversation
[REQUEST URI]
[SAMPLE REQUEST BODY]
Document Details
⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.