TISC API

Référence de l’API Xanadu

Release

xanadu

ft:locale

fr-FR

ft:publication_title

Référence de l’API Xanadu

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

TISC API

Rversion finale: Xanadu

Mis à jour 1 août 2024

24 minutes de lecture

L’API TISC fournit des points de terminaison permettant d’ajouter et de récupérer des données de Threat Intelligence dans l’application Centre de sécurité des renseignements sur les menaces (TISC).

Les données récupérées par cette API peuvent être utilisées par d’autres outils de sécurité tels que les systèmes SIEM (Security Information Event Management). Les systèmes SIEM peuvent s’intégrer à l’aide de TISC cette API pour récupérer les observables liés aux menaces et TISC détecter et surveiller automatiquement ces menaces au sein du réseau d’une organisation. Cette API permet le partage bidirectionnel d’observables à partir d’outils de sécurité. Les systèmes SIEM observent une activité anormale dans l’environnement et peuvent fournir une liste des observables associés à l’activité anormale à TISC.

Cette API peut également être utilisée pour enrichir les alertes SIEM avec un contexte de renseignements sur les menaces. Par exemple, si une alerte SIEM est générée sur la base d’un trafic anormalement élevé provenant d’une adresse IP, elle peut fournir des informations supplémentaires, TISC par exemple si l’adresse IP ou le domaine impliqué est lié à des activités malveillantes connues. Ces données d’enrichissement permettent aux analystes de sécurité de trier les alertes et d’utiliser les informations contextuelles pour une correction efficace.

Cette API nécessite l’application Centre de sécurité des renseignements sur les menaces , qui est disponible sur le ServiceNow Store.

Cette API s’exécute dans l’espace de noms sn_sec_tisc .

La version actuelle de cette API est v1.

Pour plus d’informations sur l’authentification par API, reportez-vous à la section Sécurité des API REST de la section REST APIs.

Pour en savoir plus sur , reportez-vous à TISCla section Threat Intelligence Security Center.

API TISC : POST /sn_sec_tisc/threat_intel_data/add_observables

Ajoute des enregistrements sources d’observables à l’application Centre de sécurité des renseignements sur les menaces (TISC).

Les enregistrements sources des observables sont créés dans la table Source des observables [sn_sec_tisc_observable_source] et sont traités par déduplication et agrégation dans le flux de données TISC.

Remarque :

Les enregistrements sources des observables ne peuvent pas être directement mis à jour à l’aide de ce point de terminaison. Seuls de nouveaux enregistrements peuvent être créés. Par conséquent, même si seuls quelques champs nécessitent une mise à jour, tous les champs doivent toujours être inclus dans la demande.

Pour accéder à ce point de terminaison, l’appelant doit disposer du rôle sn_sec_tisc.api_obs_write_access qui, par défaut, est inclus dans le rôle d’administrateur Threat Intelligence (sn_sec_tisc.admin).

Format d'URL

URL versionnée : /api/sn_sec_tisc/{api_version}/threat_intel_data/add_observables

URL par défaut : /api/sn_sec_tisc/threat_intel_data/add_observables

Paramètres de demande pris en charge

Tableau 1. Paramètres de chemin d'accès
Nom	Description
api_version	Facultatif. Version du point de terminaison auquel accéder. Exemple : `v1` ou `v2`. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne

Tableau 2. Paramètres de requête
Nom	Description
Aucun

Tableau 3. Paramètres du corps de la demande (JSON)
Nom	Description
observables	Requis. Tableau d’objets observables à ajouter.TISC Pour chaque objet observable, un enregistrement source observable est créé si toutes les validations sont réussies, avec la source telle que définie par le source paramètre dans le corps de la demande. `"observables": [ { "attributes": {Object}, "<field>": "String" } ]` Type de données : tableau d’objets
Observables.Attributs	Paires champ-valeur contenant des données attributaires sur l’observable. Les attributs sont spécifiques à un type d’observable, comme le numéro AS pour une adresse IP ou le type de socket pour un réseau. Tous les attributs de tous les types d’observables sont pris en charge. Pour obtenir la liste complète des attributs valides, consultez la section Attributs observables ci-dessous. `"attributes": { "<field>": "<value>" }` Type de données : objet
observables.<field>	Paires champ-valeur contenant des données générales sur l’observable. Les champs qui peuvent être fournis dans ce paramètre sont communs à tous les types d’observables et sont situés dans la table Source d’observables [sn_sec_tisc_observable_source]. Les type champs et value sont requis pour tous les observables. Remarque : Suivez les instructions suivantes pour fournir des valeurs : Toutes les dates doivent être au format ISO dans le fuseau horaire UTC. Certains champs requièrent des valeurs d’une table spécifiée ou disposent d’une liste de valeurs possibles. Si des valeurs non valides sont fournies pour ces champs, l’enregistrement source de l’observable est toujours créé, mais les valeurs non valides sont ignorées. Champs valides : additional_context Contexte supplémentaire sur l’observable. attack_phases Liste des noms des phases d’attaque sous forme de valeur séparée par des virgules. Pour obtenir la liste complète des phases d’attaque valides, consultez le champ Nom de la phase de kill chain dans le tableau Phase de kill chain [sn_sec_tisc_kill_chain_phase]. Par exemple : `"attack_phases": "Lockheed Martin: Reconnaissance,Lockheed Martin: Installation"` auteur Auteur pour l’observable. fiabilité Confiance du système source dans l’exactitude des données observables. Doit être un nombre compris entre 0 et 100. description Description de l’observable. expiration_time Date d’expiration de l’enregistrement de l’observable. external_source_id ID externe de l’observable à partir du système source. first_observed Date à laquelle les données ont été vues pour la première fois. first_seen Date à laquelle cet observable a été vu pour la première fois en train d’effectuer des activités malveillantes. last_observed Date à laquelle les données ont été vues pour la dernière fois. last_seen Date à laquelle cet observable a été vu pour la dernière fois en train d’effectuer des activités malveillantes. notes Toutes les remarques supplémentaires pour l’observable. Peut être formaté en HTML. réputation Réputation de l’observable. Valeurs possibles : effacer malveillant suspect Inconnu source_reported_score Score de malveillance de l’observable signalé par le système source. Doit être un nombre compris entre 0 et 100. balises Liste de balises sous forme de valeur séparée par des virgules. Pour obtenir la liste complète des balises valides, consultez le champ Nom de la table Balise [sn_sec_tisc_tag]. Si la balise fournie n’existe pas, la balise est automatiquement créée et associée à l’observable. Taxonomies Liste des taxonomies sous forme de valeurs séparées par des virgules. Pour obtenir la liste complète des taxonomies valides, consultez le champ Valeur de taxonomie dans la table Valeur de taxonomie [sn_sec_tisc_taxonomy_value]. threat_level Niveau de menace de l’observable. Valeurs possibles : faible moyen élevé threat_severity Gravité de la menace de l’observable. Valeurs possibles : faible moyen élevé critique Tlp Niveau de sensibilité des données pour l’observable utilisant le Traffic Light Protocol (TLP). Situé dans le champ Étiquette de la table Étiquette TLP [sn_sec_tisc_tlp_label]. Valeurs possibles : CLAIR VERT AMBRE AMBRE+STRICT ROUGE type Requis. Type d’observable. Pour obtenir la liste complète des types d’observables valides, consultez le champ Valeur de la table Type d’observable [sn_sec_tisc_observable_type] ou la section Attributs des observables ci-dessous. usage_categories Liste des catégories d’utilisation sous forme de valeur séparée par des virgules. Pour obtenir la liste complète des catégories d’utilisation valides, consultez le champ Catégorie d’utilisation dans la table Catégorie d’utilisation [sn_sec_tisc_usage_category]. valide Requis. Valeur associée à l’observable, telle qu’une adresse IP ou une URL. Type de données : chaîne
source	Requis. La source qui a détecté les observables à l’origine, par exemple un système SIEM. La source est utilisée pour tous les observables répertoriés dans la demande d’API. Les sources fournies dans le corps de la demande sont ajoutées à la table Intégration d’API [sn_sec_tisc_api_integration]. Type de données : chaîne

En-têtes

Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

Tableau 4. En-têtes de demandes
En-tête	Description
Accepter	Format de données du corps de la réponse. Prend uniquement en charge application/json.
Content-Type	Format de données du corps de la demande. Prend uniquement en charge application/json.

Tableau 5. En-têtes de réponses
En-tête	Description
Aucun

Codes d'état

Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

Tableau 6. Codes d'état
Code d'état	Description
200	Réussi. La demande a été correctement traitée.
400	Demande incorrecte. Les paramètres de la demande ne sont pas valides ou le JSON du corps de la demande comporte une erreur syntaxique. Pour afficher les détails de l’erreur, consultez le error paramètre dans le corps de la réponse.
401	Non autorisé. L’authentification de l’utilisateur n’est pas valide. Vérifiez le nom d’utilisateur et le mot de passe ou le jeton OAuth.
403	Interdit. Il manque un rôle requis à l’utilisateur appelant. Le rôle sn_sec_tisc.api_obs_write_access est requis pour accéder à ce point de terminaison.
429	Trop de demandes. Le nombre de demandes d’API dépasse la limite de taux de l’API. Par défaut, la limite est de 100 demandes par heure.
500	Erreur interne du serveur. Consultez les journaux d’application dans la table Journal [syslog] pour plus d’informations sur l’erreur.

Paramètres de corps de réponse (JSON)


Nom	Description
erreur	Informations erronées. Ce paramètre n’est renvoyé qu’en cas d’échec de la demande. `"error": { "message": "String", "detail": "String" }` Type de données : objet
message.erreur	Message d’erreur indiquant le motif de l’échec de la demande. Type de données : chaîne
error.detail	Détails supplémentaires sur les raisons de l’échec de la demande. Type de données : chaîne
error_records	Détails sur les observables inclus dans la demande qui n’ont pas pu être ajoutés à TISC. `"error_records": [ { "error_message": "String", "type": "String", "value": "String" } ]` Type de données : tableau d’objets
error_records.error_message	Message d’erreur qui explique pourquoi un enregistrement n’a pas pu être créé pour l’observable. Type de données : chaîne
error_records.type	Type d’observable. Pour obtenir la liste complète des types d’observables valides, consultez le champ Valeur de la table Type d’observable [sn_sec_tisc_observable_type] ou la section Attributs des observables ci-dessous. Type de données : chaîne
error_records.valeur	Valeur associée à l’observable, telle qu’une adresse IP ou une URL. Type de données : chaîne
metadonnées	Métadonnées sur le nombre d’enregistrements créés par la demande d’API. `"metadata": { "error_records": Number, "success_records": Number, "total_records": Number }` Type de données : objet
metadata.error_records	Nombre d’observables inclus dans la demande qui n’ont pas pu être ajoutés à TISC. Type de données : nombre
metadata.success_records	Nombre d’enregistrements d’observables créés avec succès dans .TISC Type de données : nombre
metadata.total_records	Nombre total d’observables inclus dans la demande. Type de données : nombre
statut	État de la demande d’API. Valeurs possibles : `Réussite` : tous les observables ont été ajoutés avec succès à TISC. `partial_success` : certains observables ont été ajoutés avec succès à TISC. `Erreur` : aucun observable ajouté avec succès à TISC. `échec` : la demande a échoué en raison d’une demande incorrecte ou d’une erreur système. Consultez le error paramètre dans le corps de la réponse pour plus d’informations sur l’erreur. Type de données : chaîne
success_records	Détails sur les enregistrements d’observables qui ont été créés avec succès. `"success_records": [ { "sys_id": "String", "type": "String", "value": "String" } ]` Type de données : tableau d’objets
success_records.sys_id	Sys_id de l’enregistrement de l’observable. Type de données : chaîne
success_records.type	Type d’observable. Pour obtenir la liste complète des types d’observables valides, consultez le champ Valeur de la table Type d’observable [sn_sec_tisc_observable_type] ou la section Attributs des observables ci-dessous. Type de données : chaîne
success_records.valeur	Valeur associée à l’observable, telle qu’une adresse IP ou une URL. Type de données : chaîne

Attributs des observables

La table suivante répertorie les attributs valides pour chaque type d’observable.

Remarque :

Toutes les dates doivent être au format ISO dans le fuseau horaire UTC.


Type d'observable	Attributs	Type de données
Artefact	decryption_key	Chaîne
	encryption_algorithm	Chaîne
	md5_hash	Chaîne
	mime_type	Chaîne
	sha1_hash	Chaîne
	sha256_hash	Chaîne
	sha512_hash	Chaîne
	URL	Chaîne
autonomous_system_number	nom	Chaîne
autonomous_system_number	rir	Chaîne
répertoire	directory_creation_time	Date
	directory_last_accessed_time	Date
	directory_last_modified_time	Date
	encoded_path	Chaîne
domain_name	is_fqdn (Nom de domaine complet)	Booléen
domain_name	resolves_to	Chaîne
email_address	display_name	Chaîne
email_message	email_body	Chaîne
	email_recipients_bcc	Chaîne
	email_recipients_cc	Chaîne
	email_recipients_to	Chaîne
	email_sender	Chaîne
	email_subject	Chaîne
	sent_date	Date
email_subject	Aucun
fichier	encoded_file_name	Chaîne
	file_created_time	Date
	file_last_accessed_time	Date
	file_last_modified_time	Date
	file_name	Chaîne
	magic_number	Chaîne
	md5_hash	Chaîne
	mime_type	Chaîne
	sha1_hash	Chaîne
	sha256_hash	Chaîne
	sha512_hash	Chaîne
ip_v4_address	as_number	Chaîne
ip_v4_address	mac_address	Chaîne
ip_v4_cidr	as_number	Chaîne
ip_v4_cidr	mac_address	Chaîne
ip_v6_address	as_number	Chaîne
ip_v6_address	mac_address	Chaîne
ip_v6_cidr	as_number	Chaîne
ip_v6_cidr	mac_address	Chaîne
mac_address	Aucun
md5_hash	Aucun
mutex_name	Aucun
réseau	destination_bytes_count	Entier
	destination_packets_count	Entier
	destination_port
	end_time	Date
	http_message_body_length	Entier
	http_request_header	Chaîne
	http_request_method	Chaîne
	http_request_value	Chaîne
	http_request_version	Chaîne
	network_source	Chaîne
	network_destination	Chaîne
	icmp_code_byte	Chaîne
	icmp_type_byte	Chaîne
	is_network_active	Booléen
	is_socket_blocking	Booléen
	is_socket_listening	Booléen
	network_protocols	Chaîne
	socket_address_family	Chaîne Valeurs possibles : af_unspec af_inet af_ipx af_appletalk af_netbios af_inet6 af_irda af_bth
	socket_descriptor	Entier
	socket_handle	Entier
	socket_options	Chaîne
	socket_type	Chaîne Valeurs possibles : service_kernel_driver service_file_system_driver service_win32_own_process service_win32_share_process
	source_bytes_count	Entier
	source_packets_count	Entier
	source_port	Chaîne
	start_time	Date
	tcp_destination_flags	Chaîne
	tcp_source_flags	Chaîne
autre	Aucun
Processus	aslr_enabled	Booléen
	command_line	Chaîne
	Mot de passe CWD (répertoire de travail actuel)	Chaîne
	dep_enabled	Booléen
	environment_variables	Chaîne
	is_hidden	Booléen
	owner_sid	Chaîne
	pid (ID du processus)	Chaîne
	Priorité	Chaîne
	process_created_time	Date
	service_descriptions	Chaîne
	service_display_name	Chaîne
	service_group_name	Chaîne
	service_name	Chaîne
	service_start_type	Chaîne Valeurs possibles : service_auto_start service_boot_start service_demand_start service_disabled service_system_alert
	service_status	Chaîne Valeurs possibles : service_continue_pending service_pause_pending service_paused service_running service_start_pending service_stop_pending service_stopped
	service_type	Chaîne Valeurs possibles : service_kernel_driver service_file_system_driver service_win32_own_process service_win32_share_process
	startup_info	Chaîne
	windows_integrity_level	Chaîne Valeurs possibles : faible moyen élevé système
	window_title	Chaîne
sha1_hash	Aucun
sha256_hash	Aucun
sha512_hash	Aucun
logiciel	cpe (Common Platform Enumeration)	Chaîne
	supported_languages	Chaîne
	SWID (en anglais seulement) (Identification logicielle)	Chaîne
	vendor	Chaîne
	version	Chaîne
URL	Aucun
user_account	account_created_time	Date
	account_expiry_time	Date
	account_type	Chaîne
	can_escalate_privileges	Booléen
	credentials_last_changed_time	Date
	display_name	Chaîne
	first_login_time	Date
	is_account_disabled	Booléen
	is_privileged	Booléen
	is_service_account	Booléen
	last_login_time	Date
	account_login	Chaîne
	user_id	Chaîne
windows_registry_key	key_modified_time	Date
	registry_value	Chaîne
	subkeys_count	Entier
x509_certificate	authority_key_identifier	Chaîne
	basic_constraints	Chaîne
	certificate_policies	Chaîne
	crl_distribution_points	Chaîne
	extended_key_usage	Chaîne
	inhibit_any_policy	Chaîne
	émetteur	Chaîne
	issuer_alternative_name	Chaîne
	is_self_signed	Booléen
	key_usage	Chaîne
	name_constraints	Chaîne
	policy_constraints	Chaîne
	policy_mappings	Chaîne
	private_key_usage_valid_from	Date
	private_key_usage_valid_until	Date
	signature_algorithm	Chaîne
	objet	Chaîne
	subject_alternative_name	Chaîne
	subject_directory_attributes	Chaîne
	subject_key_identifier	Chaîne
	subject_public_key_algorithm	Chaîne
	subject_public_key_exponent	Entier
	subject_public_key_modulus	Chaîne
	valid_from	Date
	valid_until	Date
	version	Chaîne

Demande cURL

Cet exemple de demande contient trois observables pour lesquels créer des enregistrements dans .TISC

curl 'http://instance.servicenow.com/api/sn_sec_tisc/v1/threat_intel_data/add_observables' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
--data '{
   "source": "Sentinel",
   "observables": [
      {
         "value": "1.2.1.45",
         "type": "ip_v4_address",
         "reputation": "malicious",
         "confidence": "90",
         "tags": "critical,important",
         "taxonomies": "MITRE: T121",
         "attack_phases": "Lockheed Martin: Reconnaissance",
         "usage_categories": "Infected Bot",
         "first_seen": "2023-10-14T18:01:34.000Z",
         "attributes": {
            "as_number": "14280"
         }
      },
      {
         "value": "https://example.com",
         "type": "url",
         "tags": "important",
         "confidence": "50",
         "reputation": "malicious"
      },
      {
         "value": "1.1.1.1",
         "type": "ip_add",
         "confidence": "50",
         "reputation": "malicious"
      }
   ]
}'

Deux des trois observables ont été ajoutés avec succès à TISC. Un enregistrement n’a pas été créé, car le type de l’observable n’est pas valide.

{
   "status": "partial_success",
   "metadata": {
      "total_records": 3,
      "success_records": 2,
      "error_records": 1
   },
   "success_records": [
      {
         "value": "1.2.1.45",
         "type": "ip_v4_address",
         "sys_id": "e519392643e642102164e0ea78b8f29d"
      },
      {
         "value": "https://example.com",
         "type": "url",
         "sys_id": "ad1979ae43ea42102164e0ea78b8f241"
      }
   ],
   "error_records": [
      {
         "value": "1.1.1.1",
         "type": "ip_va",
         "error_message": "The 'type' field value is invalid"
      }
   ]
}

API TISC : POST/sn_sec_tisc/threat_intel_data/OBSERVABLES

Récupère les données observables, y compris les relations entre les observables et d’autres données Threat Intelligence telles que les objets STIX (Structured Threat Information Expression).

Les observables renvoyés dans la réponse sont triés sys_id par ordre croissant.

Pour plus d’informations sur les observables et les objets STIX, reportez-vous à la section IoC Repository.

Pour accéder à ce point de terminaison, l’appelant doit disposer du rôle sn_sec_tisc.api_obs_read_access qui, par défaut, est inclus dans le rôle d’administrateur Threat Intelligence (sn_sec_tisc.admin).

Format d'URL

URL versionnée : /api/sn_sec_tisc/{api_version}/threat_intel_data/observables

URL par défaut : /api/sn_sec_tisc/threat_intel_data/observables