오픈소스 관리 자동화 환경 구성: cdxgen + Dependency-Track

오픈소스 관리를 처음 시작하는 기업이 하루 안에 기본 자동화 환경을 갖출 수 있는 도구 조합으로 cdxgen + Dependency-Track을 권장합니다.

이 가이드는 설치·설정부터 라이선스·취약점 점검 환경 구성, 일상 운영까지 단계별로 안내합니다.

왜 cdxgen + Dependency-Track인가

오픈소스 관리의 핵심은 두 가지입니다.

1. 무엇이 들어있는지 파악 — SBOM(Software Bill of Materials) 생성
2. 위험 요소 지속 모니터링 — 취약점(CVE)·라이선스 정책 위반 탐지

cdxgen은 1번을, Dependency-Track은 2번을 담당합니다. 두 도구 모두 Apache-2.0 라이선스의 무료 오픈소스입니다.

전체 자동화 흐름

flowchart TD
    A["개발자 PC / CI·CD 파이프라인"] --> B["cdxgen 실행\n소스코드·컨테이너 이미지 스캔"]
    B -->|"CycloneDX SBOM (.json)"| C["Dependency-Track\n중앙 서버 자동 분석"]
    C --> D["취약점(CVE) 탐지\n→ 담당자 알림"]
    C --> E["라이선스 정책 위반\n→ 검토 요청"]

    style A fill:#2d3748,color:#fff
    style B fill:#2b6cb0,color:#fff
    style C fill:#2b6cb0,color:#fff
    style D fill:#c53030,color:#fff
    style E fill:#744210,color:#fff

이 조합을 선택한 이유

다른 도구와의 비교: FOSSology, SW360 등도 강력한 도구이지만 초기 설정 복잡도가 높습니다. 이 가이드의 조합은 하루 안에 기본 환경을 갖출 수 있도록 최소화했습니다. 각 도구의 상세 기능은 cdxgen 가이드와 Dependency-Track 가이드를 참고하세요.

Dependency-Track 설치

사전 준비: Docker 환경

Dependency-Track은 Docker Compose로 실행합니다. Docker가 없다면 Rancher Desktop을 설치합니다 (macOS·Windows, 무료). 설치 후 터미널에서 아래 명령으로 정상 설치를 확인합니다.

docker --version

docker compose 명령어 호환성: Docker Desktop·Rancher Desktop 환경에서는 docker compose(플러그인)를 사용합니다. macOS에서 Homebrew나 Colima로 Docker를 설치한 경우 docker-compose(하이픈)를 사용해야 할 수 있습니다. 이 가이드의 모든 docker compose 명령이 실패하면 docker-compose로 대체하세요.

설치 및 실행

홈 디렉토리에 전용 폴더를 만들고 공식 설정 파일을 받아 실행합니다.

# 1. 작업 폴더 생성 (홈 디렉토리 기준)
mkdir ~/dependency-track && cd ~/dependency-track

# 2. 공식 docker-compose.yml 다운로드
curl -LO https://raw.githubusercontent.com/DependencyTrack/dependency-track/HEAD/src/main/docker/docker-compose.yml

# 3. 실행 (처음 실행 시 이미지 다운로드로 1~2분 소요)
docker compose up -d

API 서버는 포트 8081, 프론트엔드는 포트 8080에서 실행됩니다.

초기 로그인

브라우저에서 http://localhost:8080 접속합니다.

초기 계정 admin / admin으로 로그인합니다. 로그인 직후 비밀번호 변경 화면이 자동으로 표시됩니다. 즉시 새 비밀번호로 변경하세요.

브라우저에서 로그인이 정상적으로 되지 않는 경우, API 서버(8081 포트)가 완전히 기동될 때까지 추가로 1~2분 대기 후 재시도하세요.

서버 관리

# 시작 (PC 재부팅 후)
cd ~/dependency-track && docker compose up -d

# 중지
docker compose down

# 상태 확인
docker compose ps

초기 설치 후 NVD 등 취약점 데이터베이스 동기화에 최소 24시간 이상 소요됩니다. 서버 로그에 Mirroring 메시지가 출력되는 것은 정상입니다. 동기화 완료 전에는 취약점이 탐지되지 않을 수 있습니다.

Vulnerability Sources 최소 권장 설정

기본값으로 다수의 취약점 소스가 활성화되어 있습니다. 처음부터 모두 켜면 중복 알림이 과도하게 발생하여 관리 부담이 커집니다.

권장: 초기에는 NVD + GitHub Advisories 중심으로 시작

Administration → Vulnerability Sources에서 아래 표를 참고하여 설정합니다.

운영 팁: 6개월 이상 운영 후 탐지 누락이 있다고 판단되면 OSV를 추가 활성화하세요. 처음부터 전부 켜는 것보다 점진적으로 확장하는 방식을 권장합니다.

NVD (필수): API 미러링으로 설정

Enable mirroring via API가 OFF이면 구버전 feed 방식으로 동작할 수 있어 최신 환경에서는 동기화 실패 또는 지연 가능성이 큽니다. 반드시 API 미러링을 사용하세요.

• Enable NVD mirroring: ON
• Enable mirroring via API: ON
• API endpoint: https://services.nvd.nist.gov/rest/json/cves/2.0 (기본값 유지)
• API key: NVD에서 발급받은 키 입력
• Additionally download feeds: OFF 유지 (일반 운영에서는 불필요)

적용 후 Last Modification이 비어 있으면 초기 동기화가 진행 중일 수 있습니다. 초기 동기화 완료 후 값이 채워지는지 확인하세요.

GitHub Advisories: PAT 없으면 동작하지 않음

GitHub Advisory 미러링은 Personal Access Token(PAT) 입력이 필요합니다.

• Enable GitHub Advisory mirroring: ON
• Enable vulnerability alias synchronization: ON 유지
• Personal Access Token: classic PAT(ghp_...) 입력

참고: fine-grained PAT(github_pat_...)은 환경에 따라 인증 이슈가 보고되어 classic PAT 사용을 권장합니다.

Google OSV: Ecosystem 선택이 있어야 활성화

OSV는 Ecosystem을 하나 이상 선택해야 실제 미러링이 동작합니다.

• Select ecosystem to enable Google OSV Advisory mirroring: ON
• Enable vulnerability alias synchronization: ON
• OSV Base URL: 기본값 유지
• Ecosystem(예시): PyPI, npm, Maven, Go, Linux (환경에 따라 NuGet, RubyGems, crates.io 추가)

적용 순서 (권장)

# 설정 저장 후 미러링 로그 확인
docker compose logs -f dtrack-apiserver | grep -iE "nvd|github|osv|mirror"

필요 시 초기 설정 반영을 위해 API 서버를 재시작합니다.

docker compose restart dtrack-apiserver

라이선스 정책 설정

Dependency-Track의 정책 엔진(Policy Engine)을 사용하면 라이선스 위반을 자동으로 탐지할 수 있습니다.

좌측 메뉴 → Policy Management → 화면 우측 상단 Create Policy 클릭

정책 1: Copyleft 라이선스 경고

독점 소프트웨어에 Copyleft 라이선스 컴포넌트가 포함되면 소스 공개 의무가 발생할 수 있습니다. 검토 트리거를 위한 경고로 설정합니다.

정책 기본 설정:

Create 버튼으로 정책 저장 후, 생성된 정책을 클릭하여 상세 화면으로 진입합니다. Conditions 섹션에서 + Add Condition을 클릭하여 라이선스마다 조건을 하나씩 추가합니다.

WARN으로 설정하면 빌드가 중단되지 않고 검토 요청 알림만 발송됩니다.

정책 2: 상업적 사용 제한 라이선스 차단

상업적 사용 자체를 제한하는 라이선스는 처음부터 사용을 막아야 합니다. 같은 방법으로 두 번째 정책을 생성합니다.

FAIL로 설정하면 해당 컴포넌트를 포함한 프로젝트에 위반 표시가 나타납니다.

정책 적용 범위: 정책 생성 후 Projects 탭에서 특정 프로젝트에 적용하거나, Portfolio 전체에 적용할 수 있습니다.

SKT SBOM Scanner로 빠르게 시작하기 (Easy Mode)

cdxgen을 직접 설치하지 않고 Docker만으로 SBOM을 생성하는 방법입니다. SK텔레콤이 공급망 관리를 위해 개발한 오픈소스 도구로, Node.js 설치 없이 소스코드·Docker 이미지·바이너리를 분석하여 CycloneDX JSON을 바로 출력합니다.

사전 준비

Docker v20.10 이상 및 약 4–5 GB 디스크 여유 공간이 필요합니다. 첫 실행 시 Docker 이미지 다운로드로 5–10분 소요됩니다.

설치 및 실행

# Linux / macOS
curl -O https://raw.githubusercontent.com/sktelecom/sbom-tools/main/scripts/scan-sbom.sh
chmod +x scan-sbom.sh

# 소스코드 분석 (프로젝트 루트에서 실행)
./scan-sbom.sh --project "MyApp" --version "1.0.0" --generate-only
# 결과: MyApp_1.0.0_bom.json 생성

:: Windows
curl -O https://raw.githubusercontent.com/sktelecom/sbom-tools/main/scripts/scan-sbom.bat
scan-sbom.bat --project "MyApp" --version "1.0.0" --generate-only

Docker 이미지, 바이너리·펌웨어, RootFS 분석도 지원합니다.

# Docker 이미지 분석
./scan-sbom.sh --target "myapp:v1.0" --project "MyApp" --version "1.0" --generate-only

# 펌웨어 분석
./scan-sbom.sh --target firmware.bin --project "RouterOS" --version "2.0" --generate-only

Dependency-Track에 업로드

생성된 *_bom.json 파일을 아래 명령으로 업로드합니다.

curl -X "POST" "http://localhost:8081/api/v1/bom" \
  -H "X-Api-Key: ${DT_API_KEY}" \
  -F "autoCreate=true" \
  -F "projectName=MyApp" \
  -F "projectVersion=1.0.0" \
  -F "bom=@MyApp_1.0.0_bom.json"

지원 언어

Java, Python, Node.js, Go, Rust, Ruby, PHP, .NET, C/C++(패키지 매니저 사용 시)를 한 번에 분석합니다. C/C++ 헤더 직접 관리 방식·정적 링크 바이너리는 감지에 한계가 있습니다.

소스: github.com/sktelecom/sbom-tools (Apache-2.0)

cdxgen SBOM 생성 및 자동 업로드

API Key 발급

자동화 스크립트가 Dependency-Track에 SBOM을 업로드하려면 API Key가 필요합니다.

Administration → Access Management → Teams

1. + Create Team 클릭 → 팀 이름 Automation Agents 입력 후 Create
2. 생성된 팀을 클릭하여 상세 화면 진입
3. Permissions 섹션에서 아래 두 항목 체크:
   • BOM_UPLOAD (SBOM 업로드 권한)
   • PROJECT_CREATION_UPLOAD (프로젝트 자동 생성 권한)
4. API Keys 섹션 → + Create API Key 클릭

생성된 키(odt_publicId_... 형식)를 복사하여 안전한 곳에 보관합니다. 키는 생성 직후에만 전체 값을 확인할 수 있습니다.

cdxgen 설치

npm install -g @cyclonedx/cdxgen

Node.js가 없는 환경에서는 Docker 이미지를 사용할 수 있습니다. 자세한 설치 방법은 cdxgen 가이드를 참고하세요.

SBOM 생성 및 업로드 스크립트

아래 스크립트를 scan-upload.sh로 저장하면 SBOM 생성과 업로드를 한 번에 처리합니다.

버전 호환성: cdxgen 최신 버전(v12+)은 CycloneDX 1.7 형식을 기본 생성하지만, Dependency-Track v4.14 기준 CycloneDX 1.6까지 지원합니다. --spec-version 1.6 옵션을 반드시 지정하세요.

#!/bin/bash
# 사용법: ./scan-upload.sh <프로젝트명> <버전>
# 예시:   ./scan-upload.sh "my-app" "1.0.0"

PROJECT_NAME="${1:?프로젝트명을 입력하세요}"
PROJECT_VERSION="${2:?버전을 입력하세요}"
DT_URL="http://localhost:8081"
API_KEY="${DT_API_KEY:?환경변수 DT_API_KEY를 설정하세요}"

# SBOM 생성
echo "[1/2] SBOM 생성 중..."
cdxgen -r --spec-version 1.6 -o sbom.json .

if [ ! -s sbom.json ]; then
  echo "SBOM 생성 실패: package.json, pom.xml 등 의존성 파일이 있는지 확인하세요."
  exit 1
fi

# Dependency-Track 업로드
echo "[2/2] Dependency-Track 업로드 중..."
RESPONSE=$(curl -s -X POST "${DT_URL}/api/v1/bom" \
  -H "X-Api-Key: ${API_KEY}" \
  -F "autoCreate=true" \
  -F "projectName=${PROJECT_NAME}" \
  -F "projectVersion=${PROJECT_VERSION}" \
  -F "bom=@sbom.json")

if echo "${RESPONSE}" | grep -q '"token"'; then
  echo "업로드 완료: http://localhost:8080 에서 결과를 확인하세요."
else
  echo "업로드 실패: ${RESPONSE}"
  exit 1
fi

# 실행 방법
export DT_API_KEY="발급받은_API_KEY"
chmod +x scan-upload.sh
./scan-upload.sh "my-app" "1.0.0"

업로드 후 Dependency-Track에서 프로젝트가 자동 생성된 것을 확인합니다.

결과 확인 및 일상 운영

대시보드 개요

http://localhost:8080 → Dashboard

취약점 Triage 기준

Projects → 프로젝트 선택 → Audit Vulnerabilities 탭

무조건 모든 Critical 취약점을 긴급 처리할 필요는 없습니다. 아래 3단계로 판단합니다.

flowchart TD
    A["취약점 발견"] --> B{"실제 사용 중인\n버전인가?"}
    B -- 아니오 --> C["Not Affected 처리\n(스캐너 오탐)"]
    B -- 예 --> D{"취약한 기능을\n우리 코드가 호출하는가?"}
    D -- 아니오 --> E["Not Affected 처리\n+ 사유 Comment 기록"]
    D -- 예 --> F{"패치 버전이\n존재하는가?"}
    F -- 예 --> G["Exploitable 설정\n개발팀에 업그레이드 요청"]
    F -- 아니오 --> H["In Triage 설정\n완화 조치 검토"]

    style C fill:#276749,color:#fff
    style E fill:#276749,color:#fff
    style G fill:#c53030,color:#fff
    style H fill:#744210,color:#fff

라이선스 정책 위반 대응

좌측 메뉴 → Policy Violation Audit에서 전사 위반 항목을 확인합니다.

• WARN (경고): 개발팀과 라이선스 사용 여부 협의 후 문제없으면 Approved 처리
• FAIL (차단): 해당 컴포넌트를 허용 라이선스 버전으로 교체 요청

일상 점검 체크리스트