指南

按顺序介绍安装 OSCAR 后开发团队和安全团队要做的事。请将下文中的地址 https://oscar.example 和密钥 <API key> 替换为您实际安装环境中的值。

整体流程

三种构建方式都通过相同的三个步骤上传 SBOM，因此无论来自哪种构建，在 OSCAR 中看起来都一样。

上传 — POST /api/v1/bom（项目不存在时自动创建：autoCreate=true）
查询 — GET /api/v1/project/lookup?name=…&version=… 返回项目标识符
打标签 — PATCH /api/v1/project/{uuid} 设置分类 (classifier)、描述和标签

上传的只是组件清单。SBOM 包含依赖库的名称、版本和哈希——绝不包含源代码。

获取 API 密钥

安全管理员在 OSCAR 中打开 Administration → Access Management → Teams，选择一个团队并生成 API 密钥。按用途分别使用不同的密钥，可将权限控制在最小范围。

用途	权限
从构建上传 SBOM	`BOM_UPLOAD` · `PROJECT_CREATION_UPLOAD` · 打标签还需 `VIEW_PORTFOLIO` · `PORTFOLIO_MANAGEMENT`
AI 查询 (MCP)	`VIEW_PORTFOLIO` · `VIEW_VULNERABILITY` · `VULNERABILITY_ANALYSIS` · `POLICY_VIOLATION_ANALYSIS`（如需上传，另加 `BOM_UPLOAD`）

在构建服务器和开发人员 PC 上，请将密钥保存在环境变量中，而不是文件里。

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # 用于构建
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # 用于 AI 查询

Maven 项目

在 pom.xml 中添加两个插件：cyclonedx-maven-plugin 在打包前生成 SBOM，exec-maven-plugin 在 install 阶段上传 SBOM。

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

上传只需一条 curl 命令（与 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

如果部署也绑定在 install 阶段，随手在本地执行一次 mvn install 就会上传到服务器。本地检查请止步于 mvn package。

npm 项目

在项目根目录放置 sbom-config.json，然后运行上传脚本 upload_sbom.py。如果 SBOM 文件 (bom.json) 不存在，脚本会先执行配置中的构建命令。

{
  "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 · 手工构建 (ssemsbom)

对于没有 pom.xml、只在 lib/ 中放有 JAR 的项目，ssemsbom CLI 会扫描这些 JAR，生成 CycloneDX 1.5 SBOM 并上传。

./install.sh                                   # 安装到 ~/.ssemsbom 并加入 PATH
ssemsbom --config sbom-config.json             # 生成 · 上传 · 打标签
ssemsbom --config sbom-config.json --no-upload # 只生成文件

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

名称如何识别

遗留 JAR 的元数据参差不齐，因此按可信度从高到低依次尝试各个来源。前面步骤已设置的值不会被后面的步骤覆盖。

文件名 — commons-lang3-3.12.0.jar → 默认的名称和版本
pom.properties — 若存在，group、名称和版本全部取自这里（最可信）
MANIFEST.MF — 仅在没有 pom 时补充版本
group 推断表 — 根据常用依赖库的名称补全 group
Implementation-Vendor-Id — 仅当 group 仍为空且看起来像域名时使用
Maven Central 哈希查询 — 仅在指定 --resolve-central 时执行（需要网络）

如果都无法识别，group 保持为 unknown。名称错误不会表现为报错，而是表现为“0 个漏洞”，因此 OSCAR 不做猜测。

标准标签

三种构建方式必须使用相同的键，才能在界面和 AI 回答中归为一组。无值标签（ant-managed 等）只附加名称。

键	含义	示例
`team`	负责团队	`core`
`category`	类别	`security`
`service-type`	服务类型	`backend` · `frontend` · `utility`
`technology`	主要技术	`java` · `javascript`
`build`	构建工具	`maven` · `npm-webpack` · `ant`
`target-host` · `target-server`	部署主机 · 服务器	`app-01`
`target-was` · `target-vendor` · `target-java`	应用服务器 · 厂商 · Java	`tomcat` · `apache` · `openjdk`
`maven-managed` · `npm-managed` · `ant-managed`	构建管理标记（无值）	—

请确保标签值与实际部署一致。“哪些服务运行在哪个应用服务器上？”这类问题正是依据它们来回答的。

连接 AI (MCP)

OSCAR MCP 服务器是运行在 Java 21 上的单个 jar。由 AI 客户端启动它，并通过 STDIO 通信。Claude Desktop 使用其配置文件 (claude_desktop_config.json)；Claude Code 使用项目中格式相同的 .mcp.json。

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

连接后，可以这样提问：

“哪些项目存在 Critical 漏洞？”
“有没有项目受 CVE-2021-44228 影响？”
“汇总一下 payment-api 的许可证策略违规情况。”
“带有 team:core 标签的项目自上周以来有什么变化？”

由于有 47 个工具，请选择支持工具调用 (tool calling) 的内部模型。不支持的模型不会调用工具，而是靠猜测作答。

许可证翻译引擎

许可证全文由三种引擎之一翻译，可在安装时根据贵司的政策选择。

引擎	运行位置	适用场景
Ollama	您的服务器	连待翻译的文本也必须留在内网
LM Studio	您的服务器（在 Apple Silicon 上速度快）	同上
Gemini	外部 API	内部没有 GPU，且允许调用外部服务

译文以 【中文译文】 + 【原文 (Original)】 的形式附加。如果无法连接引擎，则只显示原文。

常见问题

源代码会上传到 OSCAR 吗？

不会。SBOM 只包含依赖库的名称、版本和哈希。

能在隔离内网中使用吗？

可以。OSCAR 运行在内网中，只有漏洞数据通过网络桥接流入。内部数据没有任何流出的通道。

AI 答错了怎么办？

AI 只调用工具获取引擎的数据，不会自行判断。回答中会显示所用的工具名称，您可以在界面上核对同样的数据。

分析引擎 (Dependency-Track) 可以升级吗？

可以。OSCAR 在引擎前方工作且不修改引擎，因此可以直接安装官方发布版本。上传历史会读取引擎数据库的一部分，所以升级后请确认一次历史记录仍在持续累积。

商业或内部 JAR 怎么办？

在公共仓库和 JAR 内部都没有信息的组件无法识别，会保持为 unknown。它们可能在漏洞匹配中被遗漏，请单独跟踪管理。

还有其他问题？请发邮件至 halo@levelupsoft.com。