Utilizzo dell'API REST

6 giugno 2024

ID 204471

L'utilizzo di MDR tramite l'API REST include l'acquisizione, la creazione e l'aggiornamento di risorse, incidenti e utenti.

APRIRE IL RIFERIMENTO PER L'API REST

I metodi dell'API REST richiedono il valore client_id. È possibile ottenere il valore client_id nella sezione Informazioni token di qualsiasi token di aggiornamento in Web Console MDR.

Di seguito sono riportati esempi di script per Python e Shell che dimostrano le funzionalità principali dell'API REST:

  • Definire il percorso del certificato, l'URL dell'API REST, l'ID client e i token
  • Ottenere il token di accesso e un token di aggiornamento per l'aggiornamento successivo del token di accesso
  • Ottenere il numero di risorse
  • Ottenere l'elenco delle risorse o i dettagli delle risorse
  • Ottenere il numero di incidenti, l'elenco degli incidenti o i dettagli dell'incidente
  • Ottenere l'elenco delle risposte per l'incidente
  • Confermare, rifiutare la risposta o aggiornare l'elenco delle risposte
  • Ottenere l'elenco dei commenti per l'incidente specificato o creare un nuovo commento per l'incidente specificato

Esempio (Python):

###################################################

# Parte generale

###################################################

 

import time

import datetime

import requests

import jwt

 

# Il certificato è richiesto per l'autenticazione di una risorsa esterna

# È possibile scaricare il certificato da https://mdr.kaspersky.com,

# salvarlo sul disco e aggiungere il percorso nella variabile:

VERIFY_CERT_PATH = "C:\\tools\\DigiCert Global Root G2.crt"

 

# MDR REST API URL:

API_URL = "https://mdr.kaspersky.com/api/v1"

 

# L'ID del client e i token.

# Per i dettagli su come ottenere l'ID e i token, fare riferimento alla guida https://support.kaspersky.com/MDR/it-IT/258285.htm

CLIENT_ID = "9ed43ed54sAmpleIdf349323951f" # (Incollare il valore)

REFRESH_TOKEN = "ReFrEsHToKeN" # (Incollare il valore)

ACCESS_TOKEN = "AcCeSsToKeN" # (Incollare il valore)

 

 

###################################################

# Ottenere il token di accesso e un token di aggiornamento per l'aggiornamento successivo del token di accesso

###################################################

 

if REFRESH_TOKEN:

refresh_token_exp = jwt.decode(REFRESH_TOKEN, options={"verify_signature": False}).get("exp")

print(f"REFRESH_TOKEN data e ora di scadenza: {datetime.datetime.fromtimestamp(refresh_token_exp)}")

if refresh_token_exp > time.time():

print("REFRESH_TOKEN è attuale")

else:

print(

"Sarebbe opportuno aggiornare REFRESH_TOKEN. Prelevarlo dalla Console MDR (https://support.kaspersky.com/MDR/it-IT/258285.htm). "

)

exit()

else:

print(

"Sarebbe opportuno inserire il valore REFRESH_TOKEN. Prelevarlo dalla Console MDR (https://support.kaspersky.com/MDR/it-IT/258285.htm). "

)

exit()

 

# Verificare la presenza e la validità del token di accesso

need_update_access_token = False

if ACCESS_TOKEN:

access_token_exp = jwt.decode(ACCESS_TOKEN, options={"verify_signature": False}).get("exp")

print(f"ACCESS_TOKEN data e ora di scadenza: {datetime.datetime.fromtimestamp(access_token_exp)}")

if access_token_exp > time.time():

print("ACCESS_TOKEN è attuale")

else:

need_update_access_token = True

else:

need_update_access_token = True

 

# Se necessario, aggiornare il token di accesso e aggiornare il token per il prossimo aggiornamento del token di accesso

access_token = ACCESS_TOKEN

se need_update_access_token:

request_body = {"refresh_token": REFRESH_TOKEN}

result = requests.post(url=f"{API_URL}/{CLIENT_ID}/session/confirm", json=request_body, verify=VERIFY_CERT_PATH)

result_json = result.json()

 

if "error" in result_json:

print(result_json)

exit()

 

# È necessario salvare il token di aggiornamento per ottenere il token di accesso successivo alla scadenza del token di accesso corrente

refresh_token = result_json["refresh_token"]

print(

f'!!! Il nuovo REFRESH_TOKEN per l'orario successivo per la richiesta ACCESS_TOKEN (sostituire il valore di REFRESH_TOKEN con questo valore): "{refresh_token}"'

)

 

# È necessario un nuovo token di accesso per recuperare i dati

access_token = result_json["access_token"]

print(f'!!! Il nuovo ACCESS_TOKEN (sostituire il valore di ACCESS_TOKEN con questo valore): "{access_token}"')

 

# Il token di accesso viene aggiunto all'intestazione della richiesta

headers = {"Authorization": f"Bearer {access_token}"}

 

 

###################################################

# Ottenere il numero di risorse

###################################################

 

# La data e l'ora sono espresse in millisecondi da 1970-01-01T00:00:00Z

request_body = {

"max_last_seen": int(time.time())

* 1000, # Limitazione dell'ora massima per l'ultima visualizzazione della risorsa all'ora corrente

"min_last_seen": 1639311132000, # Limitazione dell'ora minima per l'ultima visualizzazione della risorsa con la costante - Domenica, 12 dicembre 2021 12:12:12 (GMT)

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/assets/count", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Ottenere l'elenco delle risorse

###################################################

 

request_body = {

# Parametri di ricerca:

"max_last_seen": int(time.time())

* 1000, # Limitazione dell'ora massima per l'ultima visualizzazione della risorsa all'ora corrente

"min_last_seen": 1639311132000, # Limitazione dell'ora minima per l'ultima visualizzazione della risorsa con la costante - Domenica, 12 dicembre 2021 12:12:12 (GMT)

"domain": "",

"host_names": ["MA-MDR-KES-S", "SIN-MDR-KSC"], # (Incollare il valore) Elenco nomi host

"is_isolated": False,

"network_interface": "10.70.104.1",

"os_version": "Windows", # La risorsa deve contenere la riga specificata nel nome del sistema operativo

"product": "",

"search_phrase": "mdr", # Frase da cercare per contenuto campo: "host_name", "domain", "installed_product_info", "network_interfaces", "os_version"

"statuses": ["OK", "ABSENT"], # Ricerca delle risorse con gli stati correnti elencati qui

# Opzioni per la visualizzazione dei risultati della ricerca:

"sort": "first_seen:asc", # Ordinare i risultati in base all'ora della prima occorrenza. In caso di recupero dei risultati pagina per pagina, è necessario specificare un campo per l'ordinamento che non cambierà da query a query, ad esempio "first_seen"(non specificare campi i cui valori cambiano continuamente, ad esempio il campo "last_seen"; questo può portare a risultati errati).

"page_size": 100, # Risorse per pagina - 100

"page": 1, # Ottenere la prima pagina dei risultati di ricerca

"version": 2, # Versione della soluzione

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/assets/list", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Ottenere i dettagli della risorsa

###################################################

 

request_body = {

"asset_id": "0xFA6A68CC9A9415963DE841048A3BE929", # (Incollare il valore) ID risorsa

"version": 2, # Versione della soluzione

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/assets/details", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

).json()

print(result)

 

 

###################################################

# Ottenere il numero degli incidenti

###################################################

 

request_body = {

"max_update_time": int(time.time())

* 1000, # Limitare l'ora massima dell'ultimo aggiornamento dell'incidente all'ora corrente

"min_update_time": 1639311132000, # Limitazione dell'ora minima dell'ultimo aggiornamento dell'incidente con la costante - Domenica 12 dicembre 2021 12:12:12 (GMT)

"affected_hosts": [

"MA-MDR-KES-S:0xFA6A68CC9A94145456E841048A3BE929"

], # (Incollare il valore) Elenco degli host in formato "host_name:asset_id"

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/incidents/count", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Ottenere l'elenco degli incidenti

###################################################

 

request_body = {

# Parametri di ricerca:

"max_creation_time": int(time.time())

* 1000, # Limitare l'ora massima di creazione dell'incidente all'ora corrente

"min_creation_time": 1639311132000, # Limitazione dell'ora minima per la creazione dell'incidente con la costante - Domenica 12 dicembre 2021 12:12:12 (GMT)

"asset_ids": [

"0xFA6A68CC9A9415963DE841048A3BE929"

], # (Incollare il valore) Elenco delle risorse per cui si ottengono gli incidenti

"priorities": ["HIGH"],

"resolutions": ["True positive"],

"response_statuses": ["Confirmed"],

"response_types": ["hash"],

"statuses": ["Closed"],

# Parametri per fornire risultati

"markdown_to_html": True, # Risultati in formato HTML. Se il valore è "False", i risultati sono in formato Markdown.

"sort": "creation_time:asc", # Ordinare i risultati in base alla data e all'ora di creazione dell'incidente. In caso di recupero dei risultati pagina per pagina, è necessario specificare un campo per l'ordinamento che non cambierà da query a query, ad esempio creation_time (non specificare campi i cui valori cambiano continuamente, ad esempio il campo "update_time"; questo può portare a risultati errati).

"page_size": 100, # Incidenti per pagina - 100

"page": 1, # Ottenere la prima pagina dei risultati di ricerca

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/incidents/list", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Ottenere i dettagli degli incidenti

###################################################

 

request_body = {

"incident_id": "60gWG4UBMUGN-LWUuv1m", # (Incollare il valore) ID incidente

"markdown_to_html": True, # Risultati in formato HTML. Se il valore è "False", i risultati sono in formato Markdown.

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/incidents/details", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Ottenere un elenco di reazioni per l'incidente

###################################################

 

request_body = {

"incident_id": "60gWG4UBMUGN-LWUuv1m", # (Incollare il valore) ID incidente

"page_size": 10, # Reazioni per pagina - 10

"page": 1, # Ottenere la prima pagina dei risultati di ricerca

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/responses/list", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Confermare la reazione

###################################################

 

request_body = {

"response_id": "CEgYG4UBMUGN-LWULP7W", # (Incollare il valore) ID reazione

"comment": "comment_text", # Commento da aggiungere alla reazione

"status": "Confirmed", # Nuovo stato della reazione - "Confirmed"

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/response/update", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Rifiutare la reazione

###################################################

 

request_body = {

"response_id": "CEgYG4UBMUGN-LWULP7W", # (Incollare il valore) ID reazione

"comment": "comment_text", # Commento da aggiungere alla reazione

"status": "Declined", # Nuovo stato della reazione - "Declined"

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/response/update", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

 

 

###################################################

# Aggiornare l'elenco delle reazioni

###################################################

 

request_body = {

"responses_ids": [

"CEgYG4UBMUGN-LWULP7W",

"2ESl6IgB4cAOUyXBb5IB",

], # (Incollare i valori) ID reazione

"comment": "comment_text", # Commento da aggiungere alle reazioni

"status": "Confirmed", # Nuovo stato delle reazioni - "Confirmed"

}

result = requests.post(

url=f"{API_URL}/{CLIENT_ID}/responses/update", json=request_body, headers=headers, verify=VERIFY_CERT_PATH

)

print(result.json())

Esempio (Shell):

# Ottenere il token di accesso e il nuovo token di aggiornamento

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/session/confirm -H "Content-Type: application/json" -d '{"refresh_token": "{refresh_token}"}'

# Esempio di risposta. Successivamente, è necessario utilizzare access_token per recuperare i dati e refresh_token per recuperare il nuovo token di accesso e il token di aggiornamento.

{

"access_token": "SamPLET346yoKenSamPLEToK25EnSamPLEToK35EnS",

"refresh_token": "tOKenSaMPlet259OKenS123aMPle926tOKenSaMPle"

}

 

# Ottenere il numero di risorse

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/assets/count -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"max_last_seen": 1704103200000, "min_last_seen": 1704762000000}'

 

# Ottenere l'elenco delle risorse

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/assets/list -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"max_last_seen": 1704103200000, "min_last_seen": 1704762000000, "domain": "", "host_names": ["MA-MDR-KES-S","SIN-MDR-KSC"], "is_isolated": false, "network_interface": "10.70.104.1", "os_version": "Windows", "product": "", "search_phrase": "mdr", "statuses": ["OK","ABSENT"], "sort": "first_seen:asc", "page_size": 100, "page": 1, "version": 2}'

 

# Ottenere i dettagli della risorsa

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/assets/details -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"asset_id": "0xFA6A68CC9A9415963DE841048A3BE929", "version": 2}'

 

# Ottenere il numero degli incidenti

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/incidents/count -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"max_update_time": 1704103200000, "min_update_time": 1704762000000, "affected_hosts": ["MA-MDR-KES-S:0xFA6A68CC9A9415963DE841048A3BE929"]}'

 

# Ottenere l'elenco degli incidenti

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/incidents/list -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"max_creation_time": 1704103200000, "min_creation_time": 1704762000000, "asset_ids": ["0xFA6A68CC9A9415963DE841048A3BE929"], "priorities": ["HIGH"], "resolutions": ["True positive"], "response_statuses": ["Confirmed"], "response_types": ["hash"], "statuses": ["Closed"], "markdown_to_html": true, "sort": "creation_time:asc", "page_size": 100, "page": 1}'

 

# Ottenere i dettagli degli incidenti

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/incidents/details -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"incident_id": "60gWG4UBMUGN-LWUuv1m", "markdown_to_html": true}'

 

# Ottenere un elenco di reazioni per l'incidente

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/responses/list -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"incident_id": "60gWG4UBMUGN-LWUuv1m", "page_size": 10, "page": 1}'

 

# Aggiornare la reazione

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/response/update -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"response_id": "CEgYG4UBMUGN-LWULP7W", "comment": "comment_text", "status": "Confirmed"}'

 

# Aggiornare l'elenco delle reazioni

curl -X POST https://mdr.kaspersky.com/api/v1/{client_id}/responses/update -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -d '{"responses_ids": ["CEgYG4UBMUGN-LWULP7W", "2ESl6IgB4cAOUyXBb5IB"], "comment": "comment_text", "status": "Confirmed"}'

Esempio di risposta dell'API REST con il token di accesso e il nuovo token di aggiornamento:

{

"access_token": "SamPLET346yoKenSamPLEToK25EnSamPLEToK35EnS",

"refresh_token": "tOKenSaMPlet259OKenS123aMPle926tOKenSaMPle"

}

Esempio di risposta dell'API REST con la struttura e i valori dei commenti:

[{

"comment_id": "bfu6TiNghqp",

"author_name": "John Doe",

"text": "<p>Primo commento.</p>",

"creation_time": 1601295428640

}, {

"comment_id": "bfu6TiNghqt",

"author_name": "Jane Doe",

"text": "<p>Secondo commento.</p>",

"creation_time": 1601295433441

}]

Esempio di risposta dell'API REST quando l'API REST crea un nuovo commento e invia una risposta con i dettagli del commento:

{

"comment_id": "AXTej0Qi4bfu6TiNgmvT",

"author_name": "Nome token",

"text": "Nuovo commento creato tramite l'API REST.",

"creation_time": 1601461748122

}

Vedere anche:

Scenario: esecuzione dell'autorizzazione basata su token

Hai trovato utile questo articolo?
Cosa pensi che potremmo migliorare?
Grazie per il feedback! Ci stai aiutando a migliorare.
Grazie per il feedback! Ci stai aiutando a migliorare.