Panduan

Langkah-langkah yang dilakukan tim pengembangan dan keamanan setelah OSCAR terpasang, secara berurutan. Ganti alamat https://oscar.example dan key <API key> di bawah dengan nilai dari instalasi Anda.

Alur keseluruhan

Ketiga jenis build mengunggah SBOM dengan tiga langkah yang sama, sehingga di OSCAR semuanya terlihat sama, apa pun build asalnya.

1. Unggah — POST /api/v1/bom (membuat proyek jika belum ada: autoCreate=true)
2. Cari — GET /api/v1/project/lookup?name=…&version=… mengembalikan identifier proyek
3. Beri tag — PATCH /api/v1/project/{uuid} mengatur classifier, deskripsi, dan tag

Mendapatkan API key

Admin keamanan membuka Administration → Access Management → Teams di OSCAR, memilih tim, lalu membuat API key. Key terpisah untuk setiap keperluan menjaga izin tetap sempit.

Di server build dan PC developer, simpan key di environment variable, bukan di file.

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # untuk build
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # untuk kueri AI

Proyek Maven

Tambahkan dua plugin ke pom.xml: cyclonedx-maven-plugin membuat SBOM sebelum packaging, dan exec-maven-plugin mengunggahnya pada 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>

Pengunggahan cukup dengan satu curl (perintah yang sama dengan yang dijalankan 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

Proyek npm

Letakkan sbom-config.json di root proyek dan jalankan skrip unggah upload_sbom.py. Jika file SBOM (bom.json) belum ada, skrip akan menjalankan perintah build yang dikonfigurasi terlebih dahulu.

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

Untuk proyek tanpa pom.xml yang hanya memiliki JAR di lib/, CLI ssemsbom memindai JAR tersebut, membuat SBOM CycloneDX 1.5, lalu mengunggahnya.

./install.sh                                   # memasang ke ~/.ssemsbom dan menambahkannya ke PATH
ssemsbom --config sbom-config.json             # buat · unggah · beri tag
ssemsbom --config sbom-config.json --no-upload # hanya membuat 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": "" }
}

Cara nama diidentifikasi

JAR lama membawa metadata yang tidak konsisten, sehingga sumber dicoba berurutan dari yang paling hingga paling tidak tepercaya. Nilai yang sudah diisi oleh langkah sebelumnya tidak pernah ditimpa oleh langkah berikutnya.

1. Nama file — commons-lang3-3.12.0.jar → nama dan versi default
2. pom.properties — jika ada, grup, nama, dan versi semuanya diambil dari sini (paling tepercaya)
3. MANIFEST.MF — hanya menambahkan versi jika tidak ada pom
4. Tabel inferensi grup — mengisi grup berdasarkan nama library yang banyak digunakan
5. Implementation-Vendor-Id — hanya jika masih kosong dan nilainya menyerupai domain
6. Pencarian hash di Maven Central — hanya dengan --resolve-central (memerlukan jaringan)

Jika semua cara gagal, grup tetap unknown. Nama yang salah tidak muncul sebagai error, melainkan sebagai “0 kerentanan”, karena itu OSCAR tidak menebak.

Tag standar

Ketiga jenis build harus menggunakan key yang sama agar dapat dikelompokkan bersama di UI dan dalam jawaban AI. Tag tanpa nilai (ant-managed dan sebagainya) dipasang hanya dengan namanya.

Pastikan nilai tag sesuai dengan deployment yang sebenarnya. Pertanyaan seperti “apa saja yang berjalan di server aplikasi mana?” dijawab berdasarkan tag ini.

Menghubungkan AI (MCP)

Server MCP OSCAR adalah satu jar yang berjalan di Java 21. Klien AI menjalankannya dan berkomunikasi melalui STDIO. Claude Desktop menggunakan file konfigurasinya (claude_desktop_config.json); Claude Code menggunakan .mcp.json milik proyek dengan bentuk yang sama.

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

Setelah terhubung, ajukan pertanyaan seperti:

• “Proyek mana yang memiliki kerentanan Critical?”
• “Apakah ada proyek yang terdampak CVE-2021-44228?”
• “Rangkum pelanggaran kebijakan lisensi di payment-api.”
• “Bagaimana perubahan proyek bertag team:core sejak minggu lalu?”

Dengan 47 tool, pilih model internal yang mendukung tool calling. Model tanpa kemampuan itu akan menjawab dengan menebak alih-alih memanggil tool.

Mesin terjemahan lisensi

Teks lengkap lisensi diterjemahkan oleh salah satu dari tiga mesin, yang dipilih saat instalasi sesuai kebijakan Anda.

Terjemahan ditambahkan dalam format 【Terjemahan】 + 【Teks asli (Original)】. Jika mesin tidak dapat dijangkau, hanya teks asli yang ditampilkan.

FAQ

Apakah source code diunggah ke OSCAR?

Tidak. SBOM hanya berisi nama library, versi, dan hash.

Apakah OSCAR berfungsi di jaringan air-gapped?

Ya. OSCAR berjalan di jaringan internal dan hanya data kerentanan yang dibawa masuk melalui jembatan jaringan. Tidak ada jalur bagi data internal untuk keluar.

Bagaimana jika AI menjawab dengan salah?

AI hanya memanggil tool untuk mengambil data dari mesin; AI tidak menilai sendiri. Nama tool yang digunakan ditampilkan bersama jawaban, sehingga Anda dapat memverifikasi data yang sama di layar.

Apakah mesin analisis (Dependency-Track) dapat ditingkatkan versinya?

Ya. OSCAR bekerja di depan mesin tanpa memodifikasinya, sehingga Anda dapat memasang rilis resmi apa adanya. Riwayat unggah membaca sebagian basis data mesin, jadi setelah peningkatan versi, periksa sekali bahwa riwayat tetap terus tercatat.

Bagaimana dengan JAR komersial atau internal?

Komponen yang tidak memiliki informasi di repositori publik maupun di dalam JAR tidak dapat diidentifikasi dan tetap unknown. Komponen ini mungkin terlewat dalam pencocokan kerentanan, jadi lacaklah secara terpisah.

Ada pertanyaan lain? Kirim email ke halo@levelupsoft.com.