Guide

What development and security teams do after OSCAR is installed, in order. Replace the address https://oscar.example and the key <API key> below with your installation’s values.

The overall flow

All three build types upload SBOMs with the same three steps, so in OSCAR they look the same no matter which build they came from.

1. Upload — POST /api/v1/bom (creates the project if missing: autoCreate=true)
2. Look up — GET /api/v1/project/lookup?name=…&version=… returns the project identifier
3. Tag — PATCH /api/v1/project/{uuid} sets classifier, description and tags

Getting an API key

A security admin opens Administration → Access Management → Teams in OSCAR, picks a team and generates an API key. Separate keys per purpose keep permissions narrow.

On build servers and developer PCs, keep keys in environment variables rather than files.

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # for builds
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # for AI queries

Maven projects

Add two plugins to pom.xml: cyclonedx-maven-plugin generates the SBOM before packaging, and exec-maven-plugin uploads it in the install phase.

<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>

The upload is a single curl (the same command exec-maven-plugin runs).

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

npm projects

Put an sbom-config.json in the project root and run the upload script upload_sbom.py. If the SBOM file (bom.json) is missing, it runs the configured build command first.

{
  "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 · manual builds (ssemsbom)

For projects with no pom.xml and only JARs in lib/, the ssemsbom CLI scans the JARs, generates a CycloneDX 1.5 SBOM and uploads it.

./install.sh                                   # installs to ~/.ssemsbom and adds it to PATH
ssemsbom --config sbom-config.json             # generate · upload · tag
ssemsbom --config sbom-config.json --no-upload # generate the file only

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

How names are identified

Legacy JARs carry inconsistent metadata, so sources are tried from most to least trustworthy. A value set by an earlier step is never overwritten by a later one.

1. File name — commons-lang3-3.12.0.jar → default name and version
2. pom.properties — if present, group, name and version all come from here (most trusted)
3. MANIFEST.MF — adds the version only when there is no pom
4. Group inference table — fills the group from the names of widely used libraries
5. Implementation-Vendor-Id — only if still empty and it looks like a domain
6. Maven Central hash lookup — only with --resolve-central (needs network)

If nothing works, the group stays unknown. A wrong name does not show up as an error but as “0 vulnerabilities”, so OSCAR does not guess.

Standard tags

All three build types must use the same keys to group together in the UI and in AI answers. Value-less tags (ant-managed etc.) are attached by name only.

Please keep tag values true to the real deployment. Questions like “what runs on which app server?” are answered from them.

Connecting an AI (MCP)

The OSCAR MCP server is a single jar running on Java 21. The AI client starts it and talks over STDIO. Claude Desktop uses its config file (claude_desktop_config.json); Claude Code uses the project’s .mcp.json in the same shape.

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

Once connected, ask things like:

• “Which projects have Critical vulnerabilities?”
• “Is any project affected by CVE-2021-44228?”
• “Summarize the license policy violations in payment-api.”
• “How did projects tagged team:core change since last week?”

With 47 tools, choose an in-house model that supports tool calling. Models without it answer by guessing instead of calling tools.

License translation engine

Full license texts are translated by one of three engines, chosen at installation to fit your policy.

The translation is added as 【Translation】 + 【Original】. If the engine cannot be reached, only the original is shown.

FAQ

Is source code uploaded to OSCAR?

No. An SBOM contains only library names, versions and hashes.

Does it work in air-gapped networks?

Yes. OSCAR runs in the internal network and only vulnerability data is brought in through the network bridge. There is no path for internal data to go out.

What if the AI answers wrongly?

The AI only calls tools to fetch the engine’s data; it does not judge on its own. The tool names used are shown with the answer, so you can verify the same data on screen.

Can the analysis engine (Dependency-Track) be upgraded?

Yes. OSCAR works in front of the engine without modifying it, so you install official releases as they are. Upload history reads part of the engine’s database, so after an upgrade, check once that history keeps accumulating.

What about commercial or in-house JARs?

Components with no information in public repositories or inside the JAR cannot be identified and stay unknown. They may be missed by vulnerability matching, so track them separately.

More questions? Write to halo@levelupsoft.com.