Guide

Ce que font les équipes de développement et de sécurité une fois OSCAR installé, dans l’ordre. Remplacez ci-dessous l’adresse https://oscar.example et la clé <API key> par les valeurs de votre installation.

Le flux d’ensemble

Les trois types de build envoient leurs SBOM avec les trois mêmes étapes : dans OSCAR, ils se présentent donc de la même façon, quel que soit le build d’origine.

1. Envoi — POST /api/v1/bom (crée le projet s’il n’existe pas : autoCreate=true)
2. Recherche — GET /api/v1/project/lookup?name=…&version=… renvoie l’identifiant du projet
3. Tags — PATCH /api/v1/project/{uuid} définit le classifier, la description et les tags

Obtenir une clé d’API

Un administrateur sécurité ouvre Administration → Access Management → Teams dans OSCAR, choisit une équipe et génère une clé d’API. Des clés distinctes par usage limitent les droits au strict nécessaire.

Sur les serveurs de build et les postes des développeurs, conservez les clés dans des variables d’environnement plutôt que dans des fichiers.

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # pour les builds
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # pour les requêtes IA

Projets Maven

Ajoutez deux plugins au pom.xml : cyclonedx-maven-plugin génère le SBOM avant le packaging, et exec-maven-plugin l’envoie lors de la phase install.

<plugin>
  <groupId>org.cyclonedx</groupId>
  <artifactId>cyclonedx-maven-plugin</artifactId>
  <version>2.9.1</version>
  <configuration>
    <schemaVersion>1.5</schemaVersion>
    <outputFormat>json</outputFormat>
    <outputName>${project.artifactId}-${project.version}.sbom</outputName>
  </configuration>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <goals><goal>makeBom</goal></goals>
    </execution>
  </executions>
</plugin>

L’envoi se fait en une seule commande curl (celle-là même qu’exécute exec-maven-plugin).

curl -X POST "$SSEM_OSCAR_DTRACK_URL/api/v1/bom" \
  -H "X-Api-Key: $SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR" \
  -F autoCreate=true \
  -F projectName=my-service -F projectVersion=1.0.0 \
  -F bom=@target/my-service-1.0.0.sbom.json

Projets npm

Placez un sbom-config.json à la racine du projet et lancez le script d’envoi upload_sbom.py. Si le fichier SBOM (bom.json) est absent, il exécute d’abord la commande de build configurée.

{
  "project_name": "mobile-web",
  "project_version": "5.0.2",
  "project_classifier": "APPLICATION",
  "bom_files": ["./bom.json"],
  "build_command": "npm run build",
  "tags": { "team": "front", "service-type": "frontend", "technology": "javascript",
            "build": "npm-webpack", "npm-managed": "" }
}

python3 upload_sbom.py

Ant · builds manuels (ssemsbom)

Pour les projets sans pom.xml, avec seulement des JAR dans lib/, la CLI ssemsbom analyse les JAR, génère un SBOM CycloneDX 1.5 et l’envoie.

./install.sh                                   # installe dans ~/.ssemsbom et l’ajoute au PATH
ssemsbom --config sbom-config.json             # génération · envoi · tags
ssemsbom --config sbom-config.json --no-upload # génère le fichier uniquement

{
  "project_name": "loan-batch",
  "project_version": "2.4.1",
  "lib_dirs": ["./lib", "./ext-lib"],
  "output_file": "./build/sbom.json",
  "tags": { "team": "core", "build": "ant", "target-was": "tomcat", "ant-managed": "" }
}

Comment les noms sont identifiés

Les JAR hérités portent des métadonnées incohérentes : les sources sont donc essayées de la plus fiable à la moins fiable. Une valeur fixée par une étape précédente n’est jamais écrasée par une étape suivante.

1. Nom de fichier — commons-lang3-3.12.0.jar → nom et version par défaut
2. pom.properties — s’il existe, groupe, nom et version en proviennent tous (source la plus fiable)
3. MANIFEST.MF — ajoute la version uniquement en l’absence de pom
4. Table d’inférence des groupes — complète le groupe à partir des noms de bibliothèques répandues
5. Implementation-Vendor-Id — seulement si le groupe est encore vide et que la valeur ressemble à un domaine
6. Recherche par hash dans Maven Central — seulement avec --resolve-central (accès réseau requis)

Si rien ne fonctionne, le groupe reste unknown. Un nom erroné n’apparaît pas comme une erreur mais comme « 0 vulnérabilité » : OSCAR ne devine donc pas.

Tags standard

Les trois types de build doivent utiliser les mêmes clés pour être regroupés dans l’interface et dans les réponses de l’IA. Les tags sans valeur (ant-managed, etc.) sont attachés par leur seul nom.

Veillez à ce que les valeurs des tags reflètent fidèlement le déploiement réel. Des questions comme « qu’est-ce qui tourne sur quel serveur d’applications ? » y trouvent leur réponse.

Connecter une IA (MCP)

Le serveur MCP d’OSCAR est un jar unique qui tourne sous Java 21. Le client IA le lance et communique avec lui via STDIO. Claude Desktop utilise son fichier de configuration (claude_desktop_config.json) ; Claude Code utilise le .mcp.json du projet, de même structure.

{
  "mcpServers": {
    "oscar": {
      "command": "java",
      "args": ["-jar", "/path/to/dtrack-mcp-server.jar"],
      "env": {
        "SSEM_OSCAR_DTRACK_URL": "https://oscar.example",
        "SSEM_OSCAR_DTRACK_API_KEY_MCP": "<API key>"
      }
    }
  }
}

Une fois connecté, posez par exemple ces questions :

• « Quels projets ont des vulnérabilités Critical ? »
• « Un projet est-il touché par CVE-2021-44228 ? »
• « Résume les violations de politique de licence dans payment-api. »
• « Comment ont évolué les projets tagués team:core depuis la semaine dernière ? »

Avec 47 outils, choisissez un modèle interne qui prend en charge l’appel d’outils. Les modèles qui ne le font pas répondent en devinant au lieu d’appeler les outils.

Moteur de traduction des licences

Les textes de licence complets sont traduits par l’un de trois moteurs, choisi à l’installation selon votre politique.

La traduction est ajoutée sous la forme 【Traduction】 + 【Original】. Si le moteur est injoignable, seul l’original est affiché.

FAQ

Le code source est-il envoyé à OSCAR ?

Non. Un SBOM ne contient que des noms de bibliothèques, des versions et des hashs.

Fonctionne-t-il en réseau isolé (air gap) ?

Oui. OSCAR tourne dans le réseau interne et seules les données de vulnérabilités sont importées via la passerelle réseau. Aucun chemin ne permet aux données internes de sortir.

Et si l’IA répond de travers ?

L’IA se contente d’appeler des outils pour récupérer les données du moteur ; elle ne juge pas d’elle-même. Les noms des outils utilisés s’affichent avec la réponse : vous pouvez vérifier les mêmes données à l’écran.

Peut-on mettre à jour le moteur d’analyse (Dependency-Track) ?

Oui. OSCAR fonctionne devant le moteur sans le modifier : vous installez donc les versions officielles telles quelles. L’historique des envois lit une partie de la base de données du moteur ; après une mise à jour, vérifiez une fois que l’historique continue de s’alimenter.

Qu’en est-il des JAR commerciaux ou internes ?

Les composants sans information dans les dépôts publics ni dans le JAR ne peuvent pas être identifiés et restent unknown. Ils peuvent échapper à la correspondance des vulnérabilités : suivez-les séparément.

D’autres questions ? Écrivez à halo@levelupsoft.com.