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

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기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
    • 수명주기 스테이지
    또한 'requestedBy'가 'devops'인 경우 fetchVulenrabilityInfo, fetchPackageInfo에 대한 데이터가 포함됩니다.
    • buildId- 보내는 문자열
    • lifecycleStage- 두 가지 값, 프로덕션 또는 pre_production
    • fetchVulenrabilityInfo- t/f
    • fetchPackageInfo-t/f
    요청 매개변수 가능한 값 설명
    제품 모델 ID 시스템 ID 지정된 SBOM의 루트 애플리케이션으로 매핑할 제품 모델의 시스템 ID입니다.
    비즈니스 애플리케이션 ID 시스템 ID 지정된 SBOM의 루트 애플리케이션으로 매핑할 비즈니스 애플리케이션의 시스템 ID입니다.
    businessApplicationName 비즈니스 애플리케이션 이름 지정된 SBOM의 루트 애플리케이션으로 매핑할 비즈니스 애플리케이션의 이름입니다.
    sbom소스 예를 들어 Vericode와 같은 제품 SBOM 파일의 소스입니다.
    requestedBy 도구 또는 방법론의 이름인 Jenkins입니다. "devops"를 사용하는 경우 buildId 및 lifecycleStage는 필수입니다. 업로드 요청자
    빌드 ID 문자열 요청자가 전송합니다. SBOM 빌드의 빌드 ID입니다.
    수명주기 스테이지 프로덕션 또는 pre_production 엔터티의 수명 주기 스테이지입니다.
    VulenrabilityInfo 가져오기 전신환 true인 경우 취약성 인텔리전스 통합이 트리거됩니다.
    fetchPackage 정보 전신환 true이면 패키지 인텔리전스 통합을 트리거합니다.
    업로드 API 응답: 'status' 성공/실패, 'message'(문자열), '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)
    요청 매개변수 가능한 값 설명
    bom기록 ID 시스템 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 큐 모듈 SBOM 의 수집 상태 목록에 BOM 엔터티 기록이 표시됩니다SBOM.
    • SBOM Core를 사용하는 경우 SBOM Core > BOM 수집 상태.

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

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

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

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

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

    이러한 확인이 확인되면 BOM [sn_sbom_doc] 테이블에 들어오는 SBOM 데이터가 첨부 파일로 입력됩니다.

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

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

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