사용 안내

OSCAR 를 설치한 뒤 개발팀과 보안 담당자가 하는 일을 순서대로 적었습니다. 아래의 주소 https://oscar.example 와 키 <API 키> 는 회사에 설치된 값으로 바꿔 읽으세요.

전체 흐름

세 가지 빌드 모두 같은 세 걸음으로 SBOM 을 넣습니다. 그래서 OSCAR 화면에서는 어느 빌드에서 왔는지와 상관없이 같은 모양으로 보입니다.

올리기 — POST /api/v1/bom (프로젝트가 없으면 만든다: autoCreate=true)
찾기 — GET /api/v1/project/lookup?name=…&version=… 로 프로젝트 식별자를 받는다
태그 달기 — PATCH /api/v1/project/{uuid} 로 분류 · 설명 · 태그를 붙인다

올라가는 것은 부품 목록뿐입니다. SBOM 에는 라이브러리의 이름 · 버전 · 해시가 들어가고, 소스 코드는 들어가지 않습니다.

API 키 받기

보안 담당자가 OSCAR 화면의 관리 → 접근 관리 → 팀에서 팀을 고르고 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 키>   # 빌드용
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API 키>          # AI 질의용

Maven 프로젝트

pom.xml 에 두 플러그인을 넣습니다. cyclonedx-maven-plugin 이 패키징 전에 SBOM 을 만들고, exec-maven-plugin 이 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>

올리기는 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 만 있는 프로젝트는 전용 CLI ssemsbom 이 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 을 채운다
Implementation-Vendor-Id — 그래도 비어 있고 도메인 꼴일 때만
Maven Central 해시 조회 — --resolve-central 을 줄 때만(네트워크 필요)

끝까지 알아내지 못하면 group 을 unknown 으로 둡니다. 틀린 이름은 오류가 아니라 「취약점 0건」으로 나타나기 때문에, 추측해서 채우지 않습니다.

표준 태그

세 가지 빌드가 같은 열쇠를 써야 화면과 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`	WAS · 벤더 · Java	`tomcat` · `apache` · `openjdk`
`maven-managed` · `npm-managed` · `ant-managed`	빌드 관리 표시(값 없음)	—

태그 값은 실제 배치와 맞게 적어 주세요. 「어느 WAS 에 무엇이 떠 있나」 같은 질문의 답이 이 값에서 나옵니다.

AI 연결 (MCP)

OSCAR MCP 서버는 Java 21 로 도는 jar 하나입니다. AI 클라이언트가 이 jar 를 띄우고 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 키>"
      }
    }
  }
}

연결되면 이렇게 물어봅니다.

「Critical 취약점이 있는 프로젝트 알려줘」
「CVE-2021-44228 에 영향받는 프로젝트가 있어?」
「payment-api 의 라이선스 정책 위반을 정리해줘」
「team:core 태그가 붙은 프로젝트의 지난주 대비 변화는?」

도구가 47개라 사내 LLM 을 쓸 때는 도구 호출(tool calling)을 지원하는 모델을 고르세요. 지원하지 않는 모델은 도구를 부르지 않고 짐작으로 답합니다.

라이선스 번역 엔진

라이선스 전문 번역은 세 엔진 중 하나를 씁니다. 회사의 정책에 맞게 설치할 때 고릅니다.

엔진	어디서 도나	맞는 곳
Ollama	사내 서버	번역할 글도 밖으로 내보내지 않아야 할 때
LM Studio	사내 서버(Apple Silicon 에서 빠름)	위와 같다
Gemini	외부 API	사내 GPU 가 없고 외부 호출이 허용될 때

번역은 원문 아래에 【한글 번역】 + 【원문】 형태로 붙습니다. 번역 엔진에 닿지 못하면 원문만 그대로 보입니다.

자주 묻는 것

소스 코드가 OSCAR 서버로 올라가나요?

아닙니다. SBOM 에는 라이브러리의 이름 · 버전 · 해시만 들어갑니다.

망분리 환경에서도 쓸 수 있나요?

네. OSCAR 는 업무망에 두고, 취약점 DB 만 망연계로 받아 오는 방향으로 들여옵니다. 사내 데이터가 바깥으로 나가는 경로가 없습니다.

AI 가 잘못 답하면요?

AI 는 도구를 불러 엔진의 데이터를 가져올 뿐 스스로 판정하지 않습니다. 답에 쓰인 도구 이름이 함께 보이므로 같은 내용을 화면에서 확인할 수 있습니다.

분석 엔진(Dependency-Track)을 새 판으로 올릴 수 있나요?

네. OSCAR 는 엔진을 고치지 않고 앞에서 동작하므로 엔진은 공식 판 그대로 올립니다. 업로드 이력 기능은 엔진의 DB 일부를 읽으므로, 판을 올린 뒤에는 이력이 정상으로 쌓이는지 한 번 확인합니다.

상용 · 사내 JAR 는 어떻게 되나요?

공개 저장소에도 JAR 안에도 정보가 없는 부품은 이름을 알아낼 수 없어 unknown 으로 남습니다. 이런 부품은 취약점 대조에서 빠질 수 있으니 별도로 관리하세요.

더 궁금한 점은 halo@levelupsoft.com 으로 보내 주세요.