Hướng dẫn

Những việc nhóm phát triển và nhóm bảo mật cần làm sau khi cài OSCAR, theo thứ tự. Hãy thay địa chỉ https://oscar.example và key <API key> bên dưới bằng giá trị của hệ thống bạn.

Luồng tổng thể

Cả ba kiểu build đều tải SBOM lên theo cùng ba bước, nên trong OSCAR chúng trông giống nhau bất kể đến từ build nào.

Tải lên — POST /api/v1/bom (tạo dự án nếu chưa có: autoCreate=true)
Tra cứu — GET /api/v1/project/lookup?name=…&version=… trả về định danh của dự án
Gắn thẻ — PATCH /api/v1/project/{uuid} đặt classifier, mô tả và thẻ

Chỉ danh mục thành phần được tải lên. SBOM chứa tên thư viện, phiên bản và hash — không bao giờ có mã nguồn.

Lấy API key

Quản trị viên bảo mật mở Administration → Access Management → Teams trong OSCAR, chọn một nhóm và tạo API key. Dùng key riêng cho từng mục đích giúp giới hạn quyền ở mức tối thiểu.

Mục đích	Quyền
Tải SBOM lên từ build	`BOM_UPLOAD` · `PROJECT_CREATION_UPLOAD` · để gắn thẻ cần thêm `VIEW_PORTFOLIO` · `PORTFOLIO_MANAGEMENT`
Truy vấn AI (MCP)	`VIEW_PORTFOLIO` · `VIEW_VULNERABILITY` · `VULNERABILITY_ANALYSIS` · `POLICY_VIOLATION_ANALYSIS` (thêm `BOM_UPLOAD` nếu cần tải lên)

Trên máy chủ build và PC của lập trình viên, hãy lưu key trong biến môi trường thay vì trong file.

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # cho build
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # cho truy vấn AI

Dự án Maven

Thêm hai plugin vào pom.xml: cyclonedx-maven-plugin tạo SBOM trước khi đóng gói, và exec-maven-plugin tải nó lên ở 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>

Việc tải lên chỉ là một lệnh curl (chính là lệnh mà exec-maven-plugin chạy).

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

Nếu việc triển khai cũng gắn vào phase install, một lệnh mvn install chạy tùy tiện ở máy local cũng sẽ tải lên máy chủ. Để kiểm tra ở local, hãy dừng ở mvn package.

Dự án npm

Đặt file sbom-config.json ở thư mục gốc của dự án và chạy script tải lên upload_sbom.py. Nếu chưa có file SBOM (bom.json), script sẽ chạy lệnh build đã cấu hình trước.

{
  "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 · build thủ công (ssemsbom)

Với dự án không có pom.xml mà chỉ có các JAR trong lib/, CLI ssemsbom sẽ quét các JAR, tạo SBOM CycloneDX 1.5 và tải lên.

./install.sh                                   # cài vào ~/.ssemsbom và thêm vào PATH
ssemsbom --config sbom-config.json             # tạo · tải lên · gắn thẻ
ssemsbom --config sbom-config.json --no-upload # chỉ tạo file

{
  "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ách nhận diện tên

JAR cũ có metadata không nhất quán, nên các nguồn được thử lần lượt từ đáng tin nhất đến kém tin cậy nhất. Giá trị đã được bước trước xác định sẽ không bao giờ bị bước sau ghi đè.

Tên file — commons-lang3-3.12.0.jar → tên và phiên bản mặc định
pom.properties — nếu có, group, tên và phiên bản đều lấy từ đây (đáng tin nhất)
MANIFEST.MF — chỉ bổ sung phiên bản khi không có pom
Bảng suy luận group — điền group dựa trên tên của các thư viện phổ biến
Implementation-Vendor-Id — chỉ khi group vẫn trống và giá trị trông giống tên miền
Tra hash trên Maven Central — chỉ khi dùng --resolve-central (cần mạng)

Nếu không cách nào thành công, group giữ là unknown. Một tên sai không hiện ra thành lỗi mà thành “0 lỗ hổng”, vì vậy OSCAR không đoán.

Thẻ chuẩn

Cả ba kiểu build phải dùng cùng các key để được gom nhóm trên giao diện và trong câu trả lời của AI. Thẻ không có giá trị (ant-managed v.v.) chỉ gắn tên.

Key	Ý nghĩa	Ví dụ
`team`	Nhóm phụ trách	`core`
`category`	Danh mục	`security`
`service-type`	Loại dịch vụ	`backend` · `frontend` · `utility`
`technology`	Công nghệ chính	`java` · `javascript`
`build`	Công cụ build	`maven` · `npm-webpack` · `ant`
`target-host` · `target-server`	Host · máy chủ triển khai	`app-01`
`target-was` · `target-vendor` · `target-java`	Máy chủ ứng dụng · nhà cung cấp · Java	`tomcat` · `apache` · `openjdk`
`maven-managed` · `npm-managed` · `ant-managed`	Dấu hiệu công cụ build quản lý (không có giá trị)	—

Hãy giữ giá trị thẻ đúng với môi trường triển khai thực tế. Những câu hỏi như “cái gì đang chạy trên máy chủ ứng dụng nào?” được trả lời dựa trên chúng.

Kết nối AI (MCP)

MCP server của OSCAR là một file jar duy nhất chạy trên Java 21. Ứng dụng AI khởi động nó và giao tiếp qua STDIO. Claude Desktop dùng file cấu hình của nó (claude_desktop_config.json); Claude Code dùng .mcp.json của dự án với cùng cấu trúc.

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

Sau khi kết nối, bạn có thể hỏi những câu như:

“Dự án nào đang có lỗ hổng Critical?”
“Có dự án nào bị ảnh hưởng bởi CVE-2021-44228 không?”
“Tóm tắt các vi phạm chính sách giấy phép trong payment-api.”
“Các dự án gắn thẻ team:core đã thay đổi thế nào từ tuần trước?”

Với 47 công cụ, hãy chọn mô hình nội bộ hỗ trợ gọi công cụ (tool calling). Mô hình không hỗ trợ sẽ trả lời bằng cách đoán thay vì gọi công cụ.

Engine dịch giấy phép

Toàn văn giấy phép được dịch bởi một trong ba engine, chọn khi cài đặt sao cho phù hợp với chính sách của bạn.

Engine	Chạy ở đâu	Phù hợp khi
Ollama	Máy chủ của bạn	Ngay cả văn bản cần dịch cũng phải ở trong nội bộ
LM Studio	Máy chủ của bạn (nhanh trên Apple Silicon)	Như trên
Gemini	API bên ngoài	Không có GPU nội bộ và được phép gọi ra bên ngoài

Bản dịch được thêm vào theo dạng 【Bản dịch】 + 【Bản gốc (Original)】. Nếu không kết nối được engine, chỉ bản gốc được hiển thị.

Câu hỏi thường gặp

Mã nguồn có bị tải lên OSCAR không?

Không. SBOM chỉ chứa tên thư viện, phiên bản và hash.

OSCAR có hoạt động trong mạng cách ly không?

Có. OSCAR chạy trong mạng nội bộ và chỉ dữ liệu lỗ hổng được đưa vào qua cầu nối mạng. Không có đường nào để dữ liệu nội bộ đi ra ngoài.

Nếu AI trả lời sai thì sao?

AI chỉ gọi công cụ để lấy dữ liệu từ engine; nó không tự phán đoán. Tên các công cụ đã dùng được hiển thị kèm câu trả lời, nên bạn có thể kiểm chứng cùng dữ liệu đó trên màn hình.

Có thể nâng cấp engine phân tích (Dependency-Track) không?

Có. OSCAR hoạt động phía trước engine mà không sửa đổi nó, nên bạn cài nguyên các bản phát hành chính thức. Lịch sử tải lên đọc một phần cơ sở dữ liệu của engine, vì vậy sau khi nâng cấp, hãy kiểm tra một lần xem lịch sử vẫn tiếp tục được ghi nhận.

Còn các JAR thương mại hoặc nội bộ thì sao?

Thành phần không có thông tin trên kho công khai hay bên trong JAR sẽ không nhận diện được và giữ là unknown. Chúng có thể bị bỏ sót khi đối chiếu lỗ hổng, nên hãy theo dõi riêng.

Còn câu hỏi khác? Hãy gửi email tới halo@levelupsoft.com.