REST API를 사용하여 파일 업로드 소프트웨어 자재 명세서

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 6분

    • API를 사용하여 파일을 업로드 소프트웨어 자재 명세서 하기 전에 다음 정보를 검토합니다.

    REST API 사용

    API를 사용하여 SBOM 파일을 업로드하려면 sn_sbom_core.sbom_ingest 역할이 필요합니다.

    API를 업로드합니다.

    이 API는 SBOM 파일(CycloneDX/SPDX)을 인스턴스에 업로드하고 수집하는 데 사용됩니다.

    Core 버전 4.0 SBOM 은 다음을 지원합니다.
    • CycloneDx의 XML 및 JSON(버전 1.0~1.6).
    • SPDX의 JSON(버전 2.2-2.3)
    • 주:
      32MB를 초과하는 파일은 제대로 로드되지 않을 수 있습니다.

    HTTP 메서드: (POST)

    API URL: <host_name>/api/sbom/core/upload
    주:
    ServiceNow 인스턴스 이름은 <host_name>입니다.
    아래의 모든 요청 매개변수는 선택 사항입니다. 요청 본문은 SBOM 파일 내용입니다. DevOps를 개발 프로세스의 일부로 사용하는 경우 "requestedBy" 값은 "devops"여야 합니다. DevOps에 대한 자세한 내용은 을 참조하십시오 DevOps SBOM 파일에 대한 업로드 소프트웨어 자재 명세서 . 'requestedby' 값이 'devops'(개발 작업)인 경우 다음 매개변수는 필수입니다.
    • 빌드 ID
    • lifecycleStage
    또한 'requestedBy'가 'devops'인 경우 fetchVulenrabilityInfo, fetchPackageInfo에 대한 데이터가 포함됩니다.
    • buildId- 전송하는 문자열
    • lifecycleStage- 두 개의 값, 프로덕션 또는 pre_production
    • fetchVulenrabilityInfo- t/f
    • fetchPackageInfo-t/f
    매개변수 요청 가능한 값 설명
    productModelId 시스템 ID 지정된 SBOM의 루트 애플리케이션과 매핑할 제품 모델의 시스템 ID입니다.
    비즈니스 애플리케이션 ID 시스템 ID 지정된 SBOM루트 애플리케이션과 매핑할 비즈니스 애플리케이션의 시스템 ID입니다.
    businessApplicationName(사용하지 않음) 비즈니스 애플리케이션 이름 지정된 SBOM루트 애플리케이션과 매핑할 비즈니스 애플리케이션의 이름입니다.
    sbomSource 예를 들어 다음과 같은 Veracode제품 파일의 소스입니다 SBOM .
    requestedBy 도구 또는 방법론 이름(Jenkins)입니다. "devops"를 사용하는 경우 buildId 및 lifecycleStage 는 필수입니다. 업로드 요청자
    빌드 ID 요청자가 문자열 요청자를 보냅니다. 빌드의 빌드 ID입니다 SBOM .
    lifecycleStage 생산 또는 pre_production 엔터티의 수명 주기 스테이지입니다.
    fetchVulenrabilityInfo 티/에프 true일 경우 취약성 인텔리전스 통합을 트리거합니다.
    fetchPackage 정보 티/에프 true이면 패키지 인텔리전스 통합을 트리거합니다.
    업로드 API 응답: "상태" 성공/실패, "메시지"(문자열), "bomRecordId"(성공적인 SBOM 업로드를 위해 업로드 API를 통해 반환되는 SBOM의 시스템 ID임)가 포함되었습니다.
    {

"result": {

"status": "success",

"message": "Queued for processing.",

"bomRecordId": "f207059b4393c290629aa597cbb8f247"

}

}

    상태 API

    이 API는 수집을 위해 큐에 대기 중인 SBOM의 상태 및 요약을 가져옵니다.
    • API URL: /api/sbom/core/upload/status
    • HTTP 메서드(GET)
    매개변수 요청 가능한 값 설명
    bomRecordId 시스템 ID 성공적인 SBOM 업로드를 위해 업로드 API를 통해 반환되는 SBOM 기록 ID입니다.

    상태 API 기본 응답 예시.

    
{
   "result": {
      "bomRecordId": "0407c0fea3e70a505df340f5251e617e",
      "uploadStatus": "processed",
      "additionalInfoStatus": "not_requested",
      "uploadSummary": {
         "components": {
            "added": 0,
            "removed": 0,
            "total": 70
         }
       }
    } 
}

    추가 매개변수가 있는 상태 API 응답 예시. 해당 SBOM에 대한 fetchVulenrabilityInfo를 요청한 경우 응답의 일부로 취약성 세부 항목이 표시됩니다.

    
{
 "result": {

  "bomRecordId": "93af349b4393c290629aa597cbb8f258",

  "uploadStatus": "processed",

  "additionalInfoStatus": "complete",

  "uploadSummary": {

    "components": {
 
     "added": 0,

     "removed": 0,

     "total": 3

   },

   "vulnerabilityInfo": {

    "critical": 0,

    "high": 0,

    "medium": 0,

    "low": 0,

    "none": 0

   }

  },

  "buildId": "1"

 }

}

    해당 SBOM에 대해 fetchPackageInfo를 요청한 경우 응답의 일부로 부실 및 중단된 개수가 표시됩니다.

    성공적으로 SBOM 처리된 후 업로드된 기록을 보는 위치는 사용 중인 애플리케이션에 따라 다릅니다.

    • 응답을 사용하는 SBOM 경우 작업 공간의 BOM 큐 모듈에 있는 수집 상태 목록에 BOM 엔터티 기록이 표시됩니다 SBOMSBOM .
    • SBOM Core를 사용하는 경우 SBOM Core > BOM 수집 상태.

    지원되는 SBOM 표준 및 일반 사용 정보에 대한 개선 사항

    Core 버전 4.0 SBOM 은 다음을 지원합니다.
    • CycloneDx의 XML 및 JSON(버전 1.0~1.6).
    • SPDX의 JSON(버전 2.2-2.3)
    • 주:
      32MB를 초과하는 파일은 제대로 로드되지 않을 수 있습니다.
    코어 v4.0 SBOM 부터 버전 1.0 - 1.6에 대한 CycloneDx 표준을 지원하기 위해 다음과 같은 개선 사항이 적용되었습니다.
    • (sn_sbom_core.collect_properties) 속성을 사용하여 CycloneDX SBOM 파일의 추가 정보를 임포트합니다. 이 속성은 기본적으로 비활성화되어 있습니다. 속성을 활성화하여 일반적으로 지원되지 않는 정보를 임포트합니다. 이러한 속성에서 임포트한 모든 정보는 다음에 대한 SBOM 구성요소 속성 [sn_sbom_comp_property] 테이블로 업로드됩니다.
      • 업로드된 SBOM 파일
      • 메타데이터
      • 개별 취약성
      • 구성 요소
    • 두 개의 새 라이선스 필드에서 CycloneDX 버전 1.4 이상에서 SBOM 파일에 대한 선언 및 종료된 라이선스에 대해 임포트된 구성요소 데이터를 봅니다.
      • 선언함
      • 결론
    • SBOM 구문 분석 지원은 다음 CycloneDX 구성 요소 유형에 대해 확장됩니다.
      • 버전 1.5: 플랫폼, 데이터, 장치 드라이버, 기계 학습 모델
      • 버전 1.6: 암호화
    Core 버전 3.0 SBOM 은 다음을 지원합니다.
    • CycloneDx의 XML 및 JSON(버전 1.4까지).
    • SPDX의 JSON(v2.3까지).

    호출 사용자가 성공적으로 인증되고 인스턴스에서 sn_sbom_core.sbom_ingest 역할을 ServiceNow 가지고 있는 경우 인스턴스 외부에서 API에 액세스하여 데이터를 업로드할 SBOM 수 있습니다.

    데이터가 업로드되면 구문 분석됩니다. 데이터를 구문 분석하기 전에 다음 요구 사항을 확인합니다.

    • 수신 데이터가 유효한 JSON 또는 XML인지 검사합니다.
    • BOM 형식이 지원됩니다. Core v2.1 SBOM 부터 CycloneDX(JSON 및 XML) 및 SPDX(XML) 형식이 지원됩니다.
    • 데이터를 구문 분석할 수 있도록 최소 필드를 사용할 수 있습니다.

    이러한 검사가 확인되면 수신 SBOM 데이터가 첨부 파일로 포함된 자재 명세서[sn_sbom_doc] 테이블에 항목이 생성됩니다.

    Process BOM file 비즈니스 규칙은 기록 삽입 및 데이터 구문 분석의 결과로 자동으로 트리거됩니다.
    주:
    이 비즈니스 규칙은 기본적으로 Core를 SBOM 설치하는 동안 활성화됩니다.

    에 SBOM 나열된 모든 구성 요소에는 정의된 형식이 있습니다.

    • SBOM 파일이 업로드된 구성요소는 BOM 엔터티로 간주됩니다.
    • type=library로 나열된 구성요소는 외부 공급업체 구성요소로 간주됩니다.