ErikDelfgaauw commented 1 year ago

[REQUEST URI]

Feedback: What about other regions than sentinelus(.azure-api.net)?

[SAMPLE REQUEST BODY]

Feedback: What about setting Traffic Light Protocol (TLP)? Can this be added to the sample request body?

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

ID: 22a27692-7760-d91c-1a2e-cb529e2c4cac
Version Independent ID: 7692c9a5-5c8f-baba-9aff-474e8bd8d166
Content: Import threat intelligence with the upload indicators API - Microsoft Sentinel
Content Source: articles/sentinel/upload-indicators-api.md
Service: microsoft-sentinel
GitHub Login: @austinmccollum
Microsoft Alias: austinmc

AjayBathini-MSFT commented 1 year ago

@ErikDelfgaauw Thanks for your feedback! We will investigate and update as appropriate.

ManoharLakkoju-MSFT commented 1 year ago

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

ErikDelfgaauw commented 1 year ago

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.

austinmccollum commented 1 year ago

assign:austinmccollum

austinmccollum commented 1 year ago

@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!

ManoharLakkoju-MSFT commented 1 year ago

@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.

ErikDelfgaauw commented 1 year ago

@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.

austinmccollum commented 1 year ago

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"
                }
            ]
        }
    ]
}

ErikDelfgaauw commented 1 year ago

@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!

ManoharLakkoju-MSFT commented 1 year ago

@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

MicrosoftDocs / azure-docs

Import threat intelligence with the upload indicators API: Documentation feedback #111056

Document Details

assign:austinmccollum