Viittaa vanhojen latausilmaisimien ohjelmointirajapintaan

Microsoft Sentinel latausindikaattorit ohjelmointirajapinta mahdollisti uhkatietoympäristöjen tai mukautettujen sovellusten tuomisen STIX-muodon kompromissi-indikaattorit Microsoft Sentinel työtilaan. Tämä asiakirja toimii viitteenä vanhaan ohjelmointirajapintaan.

Latausilmaisimien ohjelmointirajapintakutsussa on viisi osaa:

1. Pyynnön URI
2. HTTP-pyyntöviestin otsikko
3. HTTP-pyyntöviestin teksti
4. Vaihtoehtoisesti voit käsitellä HTTP-vastausviestin otsikon
5. Vaihtoehtoisesti voit käsitellä HTTP-vastausviestin tekstin

Asiakassovelluksen rekisteröiminen Microsoft Entra ID

Microsoft Sentinel todentaminen edellyttää kelvollista Microsoft Entra käyttöoikeustietuetta. Lisätietoja sovelluksen rekisteröinnistä on kohdassa Sovelluksen rekisteröiminen Microsoftin käyttäjätietoympäristö tai artikkelissa Perusvaiheet osana latausilmaisimia Ohjelmointirajapinnan tietoliittimen määritys.

Käyttöoikeudet

Tämä ohjelmointirajapinta edellyttää, että kutsuvan Microsoft Entra sovellukselle myönnetään Microsoft Sentinel osallistujan rooli työtilatasolla.

Luo pyyntö

Tässä osiossa käsitellään kolmea ensimmäistä niistä viidestä osasta, joita käsiteltiin aiemmin. Sinun on ensin hankittava käyttöoikeustietue Microsoft Entra ID, jota käytät pyyntöviestin otsikon kokoamiseen.

Käyttöoikeustietueen hankkiminen

Hanki Microsoft Entra käyttöoikeustietue OAuth 2.0 -todennuksella. V1.0 ja V2.0 ovat ohjelmointirajapinnan hyväksymiä kelvollisia tunnuksia.

Sovelluksen saaman tunnuksen (v1.0 tai v2.0) versio määräytyy sovelluksesi kutsuman ohjelmointirajapinnan sovellusluettelon ominaisuuden perusteellaaccessTokenAcceptedVersion. Jos accessTokenAcceptedVersion asetuksena on 1, sovelluksesi saa v1.0-tunnuksen.

Microsoftin todentamiskirjasto MSAL :n avulla voit hankkia joko v1.0- tai v2.0-käyttöoikeustietueen. Voit myös lähettää pyyntöjä REST-ohjelmointirajapintaan seuraavassa muodossa:

• VIESTI https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
• Otsikot Microsoft Entra sovelluksen käyttämiseen:
• grant_type: "client_credentials"
• client_id: {Microsoft Entra App} -asiakastunnus
• client_secret: {Microsoft Entra App} -salaisuus
• Soveltamisala: "https://management.azure.com/.default"

Jos accessTokenAcceptedVersion sovelluksen luettelotiedostossa on 1, sovelluksesi saa v1.0-käyttöoikeustietueen, vaikka se kutsuu v2-tunnuksen päätepistettä.

Resurssin/vaikutusalueen arvo on tunnuksen käyttäjäryhmä. Tämä ohjelmointirajapinta hyväksyy vain seuraavat käyttäjäryhmät:

• https://management.core.windows.net/
• https://management.core.windows.net
• https://management.azure.com/
• https://management.azure.com

Pyynnön viestin kokoaminen

Vanhasta ohjelmointirajapinnasta oli kaksi versiota. Päätepisteestä riippuen pyynnön leipätekstissä vaadittiin eri matriisin nimi. Tätä edusti myös kaksi versiota logiikkasovelluksen yhdistintoiminnosta.

1. Yhdistintoiminnon nimi: Uhkatiedot – Kompromissien latausilmaisimet (vanhentunut)
   • Päätepiste: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Ilmaisimien nimimatriisi: value

   { "sourcesystem":"TIsource-example", "value":[] }

• Liittimen toiminnon nimi: Uhkatiedot - Kompromissin (V2) latausilmaisimet (esikatselu)
  • Päätepiste: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Ilmaisimien nimimatriisi: indicators

    {
       "sourcesystem":"TIsource-example",
       "indicators":[]
    }
    

Pyynnön URI

Ohjelmointirajapinnan versiointi: api-version=2022-07-01
Päätepiste: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Menetelmä: POST

Pyynnön otsikko

Authorization: Sisältää OAuth2-haltijatunnuksen
Content-Type: application/json

Pyynnön leipäteksti

Leipätekstin JSON-objekti sisältää seuraavat kentät:

Luo ilmaisimien matriisi käyttämällä STIX 2.1 -ilmaisimen muotomääritystä, joka on tiivistetty tässä kätevästi tärkeiden osien linkkien avulla. Huomaa myös, että joillakin ominaisuuksilla, jotka ovat voimassa STIX 2.1:ssä, ei ole vastaavia ilmaisinominaisuuksia Microsoft Sentinel.

Vastausviestin käsitteleminen

Vastauksen otsikko sisältää HTTP-tilakoodin. Tästä taulukosta saat lisätietoja ohjelmointirajapintakutsun tuloksen tulkitsemisesta.

Vastauksen leipäteksti on virhesanomien matriisi JSON-muodossa:

Virheobjekti

Ohjelmointirajapinnan rajoittamista koskevat rajoitukset

Kaikkia rajoituksia sovelletaan käyttäjää kohti:

• 100 ilmaisinta pyyntöä kohden.
• 100 pyyntöä minuutissa.

Jos pyyntöjä on enimmäismäärää enemmän, 429 vastauksen otsikossa palautetaan http-tilakoodi, jossa on seuraava vastausteksti:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

Noin 10 000 ilmaisinta minuutissa on suurin sallittu siirtomäärä, ennen kuin rajoitusvirhe vastaanotetaan.

Mallipyynnön leipäteksti

{
    "sourcesystem": "test", 
    "indicators":[
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--10000003-71a2-445c-ab86-927291df48f8", 
            "name": "Test Indicator 1",
            "created": "2010-02-26T18:29:07.778Z", 
            "modified": "2011-02-26T18:29:07.778Z",
            "pattern": "[ipv4-addr:value = '172.29.6.7']", 
            "pattern_type": "stix",
            "valid_from": "2015-02-26T18:29:07.778Z"
        },
        {
            "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"
                }
            ],
            "name": "Test Indicator 2",
            "description": "This is a test indicator to demo valid fields", 
            "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"
                }
            ]
        }
    ]
}

Vastauksen leipätekstimalli, jossa on vahvistusvirhe

Jos kaikki ilmaisimet on vahvistettu, palautetaan HTTP 200 -tila, jossa on tyhjä vastausteksti.

Jos yhden tai useamman ilmaisimen vahvistus epäonnistuu, palautetaan vastauksen leipäteksti ja lisätietoja. Jos esimerkiksi lähetät matriisin, jossa on neljä ilmaisinta ja kolme ensimmäistä ovat hyviä, mutta neljännellä ei ole (pakollista id kenttää), luodaan HTTP-tilakoodi 200 vastaus seuraavan leipätekstin kanssa:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

Ilmaisimet lähetetään matriisina, joten alkaa recordIndex kohdasta 0.

Seuraavat vaiheet

Tämä ohjelmointirajapinta on vanha. Siirry käyttämään STIX-objektien ohjelmointirajapintaa uhkatietojen lataamiseen. Lisätietoja on kohdassa STIX-objektien ohjelmointirajapinta.