Guía

Lo que hacen los equipos de desarrollo y seguridad, por orden, una vez instalado OSCAR. Sustituya la dirección https://oscar.example y la clave <API key> de los ejemplos por los valores de su instalación.

El flujo general

Los tres tipos de compilación suben los SBOM con los mismos tres pasos, de modo que en OSCAR se ven igual sea cual sea la compilación de origen.

Subir — POST /api/v1/bom (crea el proyecto si no existe: autoCreate=true)
Consultar — GET /api/v1/project/lookup?name=…&version=… devuelve el identificador del proyecto
Etiquetar — PATCH /api/v1/project/{uuid} establece el clasificador, la descripción y las etiquetas

Solo se sube la lista de componentes. Un SBOM contiene nombres de bibliotecas, versiones y hashes, nunca código fuente.

Obtener una clave de API

Un administrador de seguridad abre Administration → Access Management → Teams en OSCAR, elige un equipo y genera una clave de API. Usar claves distintas para cada finalidad mantiene los permisos acotados.

Finalidad	Permisos
Subir SBOM desde las compilaciones	`BOM_UPLOAD` · `PROJECT_CREATION_UPLOAD` · para etiquetas, además `VIEW_PORTFOLIO` · `PORTFOLIO_MANAGEMENT`
Consultas a la IA (MCP)	`VIEW_PORTFOLIO` · `VIEW_VULNERABILITY` · `VULNERABILITY_ANALYSIS` · `POLICY_VIOLATION_ANALYSIS` (añada `BOM_UPLOAD` para subir)

En los servidores de compilación y en los PC de los desarrolladores, guarde las claves en variables de entorno y no en archivos.

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # para compilaciones
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # para consultas a la IA

Proyectos Maven

Añada dos plugins a pom.xml: cyclonedx-maven-plugin genera el SBOM antes del empaquetado y exec-maven-plugin lo sube en la fase 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>

La carga es un único curl (el mismo comando que ejecuta 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

Si el despliegue también está vinculado a la fase install, un mvn install local hecho sin pensar sube datos al servidor. Para comprobaciones locales, deténgase en mvn package.

Proyectos npm

Coloque un sbom-config.json en la raíz del proyecto y ejecute el script de carga upload_sbom.py. Si falta el archivo SBOM (bom.json), primero ejecuta el comando de compilación configurado.

{
  "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 · compilaciones manuales (ssemsbom)

Para proyectos sin pom.xml y con solo JAR en lib/, la CLI ssemsbom analiza los JAR, genera un SBOM CycloneDX 1.5 y lo sube.

./install.sh                                   # instala en ~/.ssemsbom y lo añade al PATH
ssemsbom --config sbom-config.json             # generar · subir · etiquetar
ssemsbom --config sbom-config.json --no-upload # solo generar el archivo

{
  "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": "" }
}

Cómo se identifican los nombres

Los JAR heredados tienen metadatos incoherentes, así que las fuentes se prueban de la más fiable a la menos fiable. Un valor fijado por un paso anterior nunca se sobrescribe en uno posterior.

Nombre de archivo — commons-lang3-3.12.0.jar → nombre y versión por defecto
pom.properties — si existe, el grupo, el nombre y la versión salen de aquí (la fuente más fiable)
MANIFEST.MF — añade solo la versión cuando no hay pom
Tabla de inferencia de grupo — completa el grupo a partir de los nombres de bibliotecas muy utilizadas
Implementation-Vendor-Id — solo si sigue vacío y parece un dominio
Búsqueda por hash en Maven Central — solo con --resolve-central (requiere red)

Si nada funciona, el grupo queda como unknown. Un nombre erróneo no aparece como error, sino como «0 vulnerabilidades», por eso OSCAR no adivina.

Etiquetas estándar

Los tres tipos de compilación deben usar las mismas claves para agruparse en la interfaz y en las respuestas de la IA. Las etiquetas sin valor (ant-managed, etc.) se añaden solo con el nombre.

Clave	Significado	Ejemplo
`team`	Equipo responsable	`core`
`category`	Categoría	`security`
`service-type`	Tipo de servicio	`backend` · `frontend` · `utility`
`technology`	Tecnología principal	`java` · `javascript`
`build`	Herramienta de compilación	`maven` · `npm-webpack` · `ant`
`target-host` · `target-server`	Host · servidor de despliegue	`app-01`
`target-was` · `target-vendor` · `target-java`	Servidor de aplicaciones · proveedor · Java	`tomcat` · `apache` · `openjdk`
`maven-managed` · `npm-managed` · `ant-managed`	Marcador de gestión de compilación (sin valor)	—

Mantenga los valores de las etiquetas fieles al despliegue real. Preguntas como «¿qué se ejecuta en cada servidor de aplicaciones?» se responden a partir de ellas.

Conectar una IA (MCP)

El servidor MCP de OSCAR es un único jar que se ejecuta en Java 21. El cliente de IA lo inicia y se comunica por STDIO. Claude Desktop usa su archivo de configuración (claude_desktop_config.json); Claude Code usa el .mcp.json del proyecto con la misma estructura.

{
  "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>"
      }
    }
  }
}

Una vez conectado, puede preguntar cosas como:

«¿Qué proyectos tienen vulnerabilidades Critical?»
«¿Algún proyecto está afectado por CVE-2021-44228?»
«Resume las infracciones de la política de licencias en payment-api.»
«¿Cómo han cambiado desde la semana pasada los proyectos con la etiqueta team:core?»

Con 47 herramientas, elija un modelo interno que admita llamadas a herramientas. Los modelos que no lo admiten responden adivinando en lugar de llamar a las herramientas.

Motor de traducción de licencias

Los textos completos de las licencias se traducen con uno de tres motores, elegido durante la instalación según su política.

Motor	Dónde se ejecuta	Ideal cuando
Ollama	Sus servidores	Incluso el texto que se traduce debe permanecer dentro
LM Studio	Sus servidores (rápido en Apple Silicon)	Igual que el anterior
Gemini	API externa	No hay GPU interna y se permiten llamadas externas

La traducción se añade como 【Traducción】 + 【Original】. Si no se puede acceder al motor, solo se muestra el original.

Preguntas frecuentes

¿Se sube código fuente a OSCAR?

No. Un SBOM contiene solo nombres de bibliotecas, versiones y hashes.

¿Funciona en redes aisladas?

Sí. OSCAR se ejecuta en la red interna y solo los datos de vulnerabilidades entran a través del puente de red. No existe ninguna ruta por la que los datos internos puedan salir.

¿Y si la IA responde mal?

La IA solo llama a herramientas para obtener los datos del motor; no emite juicios propios. Los nombres de las herramientas utilizadas se muestran junto con la respuesta, para que pueda verificar los mismos datos en pantalla.

¿Se puede actualizar el motor de análisis (Dependency-Track)?

Sí. OSCAR funciona delante del motor sin modificarlo, así que se instalan las versiones oficiales tal cual. El historial de cargas lee parte de la base de datos del motor; por eso, tras una actualización, compruebe una vez que el historial se sigue acumulando.

¿Qué pasa con los JAR comerciales o internos?

Los componentes sin información en repositorios públicos ni dentro del JAR no se pueden identificar y quedan como unknown. Pueden escapar al cotejo de vulnerabilidades, así que conviene hacerles un seguimiento aparte.

¿Más preguntas? Escriba a halo@levelupsoft.com.