Chargement de Nomenclature logicielle fichiers à l’aide d’une REST API

Rversion finale: Zurich

Mis à jour 31 juil. 2025

5 minutes de lecture

Vérifiez les informations suivantes avant de charger des Nomenclature logicielle fichiers à l’aide d’une API.

Utilisation de REST API

Pour charger un fichier SBOM avec une API, le rôle sn_sbom_core.sbom_ingest est requis.

API de chargement.

Cette API est utilisée pour charger et ingérer un fichier SBOM (CycloneDX/SPDX) dans votre instance.

La version 4.0 de SBOM Core prend en charge :

XML et JSON dans CycloneDx (versions 1.0 - 1.6).
JSON dans SPDX (versions 2.2-2.3)
Remarque :
Les fichiers de plus de 32 Mo peuvent ne pas se charger correctement.

Méthode HTTP : (POST)

URL d’API : <host_name>/api/sbom/core/upload

Remarque :

<host_name> est le nom de votre ServiceNow instance.

Tous les paramètres de demande ci-dessous sont facultatifs ; le corps de la demande est le contenu du fichier SBOM. Si vous utilisez DevOps dans le cadre de votre processus de développement, la valeur de « requestedBy » doit être « devops ». Consultez la section Chargement des Nomenclature logicielle fichiers DevOps SBOM pour plus d’informations générales sur DevOps. Si la valeur de « requestedby » est « devops » (opérations de développement), ces paramètres sont obligatoires :

ID de construction
Étape du cycle de vie

De plus, si « requestedBy » est « devops », les données pour fetchVulenrabilityInfo et fetchPackageInfo sont incluses.

buildId : chaîne que vous envoyez
Étape du cycle de vie : deux valeurs, production ou pre_production
fetchVulenrabilityInfo- t/f
fetchPackageInfo-t/f


Paramètres de demande	Valeurs possibles	Description
productModelId	ID système	ID système du modèle de produit à mapper à l’application racine du SBOM.
businessApplicationId	ID système	ID système de l’application d’entreprise à mapper à l’application racine du SBOM.
businessApplicationName (déconseillé)	Nom de votre application d’entreprise	Nom de l’application d’entreprise à mapper à l’application racine du fichier .SBOM
Source sbom	Un produit tel que Veracode, par exemple	La source de votre SBOM fichier.
requestedBy	Un outil ou le nom d’une méthodologie, Jenkins. Si vous utilisez « devops », buildId et lifecycleStage sont obligatoires.	Chargement demandé par
ID de construction	Une chaîne que le demandeur envoie.	ID de build de la SBOM build.
Étape du cycle de vie	Production ou pre_production	Étape du cycle de vie de l’entité.
fetchVulenrabilityInfo	T/F	Si vrai, déclenche l’intégration de Vulnerability Intelligence.
Informations sur fetchPackage	T/F	Si vrai, déclenche l’intégration de l’intelligence des packages.

Réponse de l’API de chargement : inclusion de la réussite/de l’échec « status », « message » (chaîne), « bomRecordId » (il s’agit de l’ID système de la nomenclature logicielle qui est renvoyé via l’API de chargement pour un chargement de nomenclature logicielle réussi).

{

"result": {

"status": "success",

"message": "Queued for processing.",

"bomRecordId": "f207059b4393c290629aa597cbb8f247"

}

}

API d’état

Cette API obtient l’état et le résumé d’une SBOM qui est en file d’attente pour l’ingestion.

URL D’API : /API/SBOM/CORE/UPLOAD/STATUS
Méthode HTTP (GET)


Paramètres de demande	Valeurs possibles	Description
bomRecordId	ID système	ID d’enregistrement SBOM renvoyé via l’API de chargement pour un chargement SBOM réussi.

Exemple de réponse par défaut de l’API d’état.


{
   "result": {
      "bomRecordId": "0407c0fea3e70a505df340f5251e617e",
      "uploadStatus": "processed",
      "additionalInfoStatus": "not_requested",
      "uploadSummary": {
         "components": {
            "added": 0,
            "removed": 0,
            "total": 70
         }
       }
    } 
}

Réponse d’API d’état avec exemple de paramètres supplémentaires. Si vous avez demandé fetchVulenrabilityInfo pour ce SBOM, vous obtenez la répartition des vulnérabilités dans le cadre de la réponse.


{
 "result": {

  "bomRecordId": "93af349b4393c290629aa597cbb8f258",

  "uploadStatus": "processed",

  "additionalInfoStatus": "complete",

  "uploadSummary": {

    "components": {
 
     "added": 0,

     "removed": 0,

     "total": 3

   },

   "vulnerabilityInfo": {

    "critical": 0,

    "high": 0,

    "medium": 0,

    "low": 0,

    "none": 0

   }

  },

  "buildId": "1"

 }

}

Si vous avez demandé fetchPackageInfo pour ce SBOM, vous obtenez des nombres périmés et abandonnés dans le cadre de la réponse.

Une fois qu’un SBOM est traité avec succès, l’endroit où vous affichez les enregistrements chargés dépend des applications que vous utilisez.

Si vous utilisez SBOM Réponse, l’enregistrement d’entité BOM s’affiche dans la liste État d’ingestion SBOM du module File d’attente BOM de l’espace SBOM de travail.
Si vous utilisez SBOM Core, accédez à SBOM principal > État de l'ingestion BOM.

Améliorations des normes prises en charge SBOM et des informations générales d’utilisation

La version 4.0 de SBOM Core prend en charge :

XML et JSON dans CycloneDx (versions 1.0 - 1.6).
JSON dans SPDX (versions 2.2-2.3)
Remarque :
Les fichiers de plus de 32 Mo peuvent ne pas se charger correctement.

À partir de la version 4.0 de SBOM Core, les améliorations suivantes ont été apportées pour prendre en charge les normes CycloneDx pour les versions 1.0 à 1.6 :

Importez des informations supplémentaires dans des fichiers SBOM CycloneDX avec la propriété (sn_sbom_core.collect_properties). Cette propriété est désactivée par défaut. Activez la propriété pour importer des informations qui ne sont généralement pas prises en charge. Toutes les informations importées à partir de ces propriétés sont téléchargées dans la table Propriété du composant SBOM [sn_sbom_comp_property] pour ce qui suit :
- Fichiers SBOM chargés
- Métadonnées
- Vulnérabilités individuelles
- Composants
Affichez les données de composant importées pour les licences déclarées et conclues pour les fichiers SBOM dans les versions 1.4 et ultérieures de CycloneDX dans deux nouveaux champs de licence :
- Déclaré
- Conclu
La prise en charge de l’analyse SBOM est étendue aux types de composants CycloneDX suivants :
- Version 1.5 : plateforme, données, pilote d’appareil, modèle d’apprentissage machine
- Version 1.6 : Cryptographique

La version 3.0 de SBOM Core prend en charge :

XML et JSON dans CycloneDx (jusqu’à la version 1.4 incluse).
JSON dans SPDX (jusqu’à la version 2.3 incluse).

Si l’utilisateur appelant est authentifié avec succès et qu’il dispose du rôle sn_sbom_core.sbom_ingest dans votre ServiceNow instance, vous pouvez accéder à l’API depuis l’extérieur de votre instance pour charger les SBOM données.

Une fois les données chargées, elles sont analysées. Avant d’analyser les données, les exigences suivantes sont vérifiées :

La validité des données entrantes est vérifiée au format JSON ou XML.
Le format BOM est pris en charge. À partir de la version 2.1 de SBOM Core, les formats CycloneDX (JSON et XML) et SPDX (XML) sont pris en charge.
Les champs minimaux sont disponibles afin que les données puissent être analysées.

Une fois ces vérifications vérifiées, une entrée est effectuée dans la table Nomenclature [sn_sbom_doc] avec les données entrantes SBOM en pièce jointe.

La Process BOM file règle métier est déclenchée automatiquement suite à l’insertion de l’enregistrement et à l’analyse des données.

Remarque :

Cette règle métier est activée lors de l’installation de SBOM Core par défaut.

Tous les composants répertoriés dans un SBOM ont un type défini.

Les composants pour lesquels SBOM des fichiers ont été chargés sont considérés comme des entités BOM.
Les composants répertoriés comme type=library sont considérés comme des composants tiers.